Languages Library
Guardian TNS C Library
Calls Reference Manual
Abstract
This manual describes the C run-time library available to TNS and accelerated programs
in the Guardian environment.
Product Version
TNS C Run-Time Library D40
Supported Releases
This manual supports D40.00 and all subsequent releases until otherwise indicated in a
new edition.
Part Number
Edition
Published
Release ID
128833
Second
July 1996
D42.00
Document History
Edition
Part Number
Product Version
Earliest Supported
Release
Published
First
115745
TNS C Run-Time Library
D40.00
November 1995
D40.00
July 1996
D40
Second
128833*
TNS C Run-Time Library
D40
New editions incorporate any updates since the previous edition.
A plus sign (+) after a release ID indicates that this manual describes function added to the base release, either by an
interim product modification (IPM) or by a new product version on a .99 site update tape (SUT).
* This edition has the same content as the previous edition with any updates; the content has been reformatted to make
it more readable online.
Ordering Information
For manual ordering information: domestic U.S. customers, call 1-800-243-6886; international customers, contact
your local sales representative.
Document Disclaimer
Information contained in a manual is subject to change without notice. Please check with your authorized Tandem
representative to make sure you have the most recent information.
Export Statement
Export of the information contained in this manual may require authorization from the U.S. Department of
Commerce.
Examples
Examples and sample programs are for illustration only and may not be suited for your particular purpose. Tandem
does not warrant, guarantee, or make any representations regarding the use or the results of the use of any examples
or sample programs in any documentation. You should verify the applicability of any example or sample program
before placing the software into productive use.
U.S. Government Customers
FOR U.S. GOVERNMENT CUSTOMERS REGARDING THIS DOCUMENTATION AND THE ASSOCIATED
SOFTWARE:
These notices shall be marked on any reproduction of this data, in whole or in part.
NOTICE: Notwithstanding any other lease or license that may pertain to, or accompany the delivery of, this
computer software, the rights of the Government regarding its use, reproduction and disclosure are as set forth in
Section 52.227-19 of the FARS Computer Software—Restricted Rights clause.
RESTRICTED RIGHTS NOTICE: Use, duplication, or disclosure by the Government is subject to the
restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at
DFARS 52.227-7013.
RESTRICTED RIGHTS LEGEND: Use, duplication or disclosure by the Government is subject to restrictions
as set forth in paragraphþ(b)(3)(B) of the rights in Technical Data and Computer Software clause in
DAR 7-104.9(a). This computer software is submitted with “restricted rights.” Use, duplication or disclosure is
subject to the restrictions as set forth in NASA FARþSUP 18-52þ227-79 (Aprilþ1985) “Commercial Computer
Software—Restricted Rights (Aprilþ1985).” If the contract contains the Clause at 18-52þ227-74 “Rights in Data
General” then the “Alternate III” clause applies.
U.S. Government Users Restricted Rights — Use, duplication or disclosure restricted by GSA ADP Schedule
Contract.
Unpublished — All rights reserved under the Copyright Laws of the United States.
New and Changed Information
This edition has the same content as the previous edition with any updates; the content
has been reformatted to make it more readable online.
Guardian TNS C Library Calls Reference Manual—128833
iii
New and Changed Information
iv
128833 —Guardian TNS C Library Calls Reference Manual
Contents
New and Changed Information
iii
About This Manual xiii
Notation Conventions xvii
1. Introduction to the Guardian TNS C Run-Time Library
2. Summary of Library Header Files
<asserth> 2-1
<ctypeh> 2-1
<errnoh> 2-2
<fcntlh> 2-5
<floath> 2-6
<limitsh> 2-8
<localeh> 2-9
<mathh> 2-9
<memoryh> 2-10
<nonstoph> 2-10
<setjmph> 2-10
<signalh> 2-10
<sqlh> 2-11
<stdargh> 2-11
<stddefh> 2-11
<stdioh> 2-11
<stdlibh> 2-12
<stringh> 2-13
<talh> 2-13
<timeh> 2-13
3. Reference to Library Calls
abort 3-1
abs 3-1
acos 3-2
asctime 3-3
asin 3-5
assert 3-6
atan 3-7
atan2 3-8
atexit 3-9
Guardian TNS C Library Calls Reference Manual—128833
v
3. Reference to Library Calls
atof 3-10
atoi 3-11
atol 3-12
bsearch 3-13
calloc 3-14
ceil 3-15
chvol (supplementary) 3-16
clearerr 3-17
clock 3-18
close (supplementary) 3-19
cos 3-20
cosh 3-21
creat (supplementary) 3-21
ctime 3-22
dec_to_longlong (supplementary)
difftime 3-25
div 3-25
ecvt (supplementary) 3-26
edfseek (supplementary) 3-27
edftell (supplementary) 3-29
edlseek (supplementary) 3-30
exit 3-31
exp 3-32
fabs 3-33
fclose 3-34
fcloseall (supplementary) 3-35
fcntl (supplementary) 3-35
fdopen (supplementary) 3-37
fdtogfn (supplementary) 3-38
feof 3-39
ferror 3-40
fflush 3-41
fgetc 3-42
fgetpos 3-43
fgets 3-44
fileno (supplementary) 3-45
floor 3-46
fmod 3-47
fopen 3-48
vi
Contents
3-24
128833 —Guardian TNS C Library Calls Reference Manual
Contents
3. Reference to Library Calls
fopen_std_file (supplementary) 3-50
fprintf 3-51
fputc 3-55
fputs 3-56
fread 3-57
free 3-58
freopen 3-59
frexp 3-61
fscanf 3-61
fseek 3-66
fsetpos 3-67
ftell 3-68
fwrite 3-69
get_assign_msg (supplementary) 3-70
get_assign_msg_by_ name (supplementary) 3-73
get_max_assign_msg_ordinal (supplementary) 3-76
get_param_by_name (supplementary) 3-76
get_param_msg (supplementary) 3-78
get_startup_msg (supplementary) 3-79
getc 3-82
getchar 3-82
getenv 3-83
gets 3-84
gmtime 3-85
heap_check (supplementary) 3-86
heap_check_always (supplementary) 3-86
heap_min_block_size (supplementary) 3-87
_is_system_trap (supplementary) 3-87
isalnum 3-88
isalpha 3-89
isascii (supplementary) 3-90
iscntrl 3-91
iscsym (supplementary) 3-92
iscsymf (supplementary) 3-93
isdigit 3-94
isgraph 3-95
islower 3-96
isprint 3-97
ispunct 3-98
Guardian TNS C Library Calls Reference Manual—128833
vii
3. Reference to Library Calls
Contents
isspace 3-99
isupper 3-100
isxdigit 3-101
labs 3-102
ldexp 3-103
ldiv 3-104
localeconv 3-105
localtime 3-106
log 3-106
log10 3-107
longjmp 3-108
longlong_to_dec (supplementary) 3-109
lseek (supplementary) 3-111
malloc 3-112
_max (supplementary) 3-113
mblen 3-114
mbstowcs 3-115
mbtowc 3-116
memchr 3-117
memcmp 3-118
memcpy 3-119
memmove 3-120
memset 3-120
memswap (supplementary) 3-121
_min (supplementary) 3-122
mktime 3-123
modf 3-125
movmem (supplementary) 3-126
__ns_backup_fopen (supplementary) 3-126
__ns_fget_file_open_state (supplementary) 3-128
__ns_fget_file_state (supplementary) 3-129
__ns_fopen_special (supplementary) 3-130
__ns_fset_file_state (supplementary) 3-132
__ns_start_backup (supplementary) 3-134
offsetof 3-136
open (supplementary) 3-137
perror 3-139
pow 3-140
printf 3-141
viii
128833 —Guardian TNS C Library Calls Reference Manual
Contents
3. Reference to Library Calls
putc 3-143
putchar 3-144
putenv 3-145
puts 3-146
qsort 3-147
raise 3-148
rand 3-149
read (supplementary) 3-150
readupdate (supplementary) 3-150
realloc 3-152
remove 3-153
rename 3-153
reply (supplementary) 3-154
repmem (supplementary) 3-155
rewind 3-156
scanf 3-157
setbuf 3-158
setjmp 3-159
setlocale 3-160
setmem (supplementary) 3-161
setnbuf (supplementary) 3-162
setvbuf 3-162
signal 3-164
sin 3-167
sinh 3-168
sprintf 3-169
sqrt 3-170
srand 3-171
sscanf 3-172
stcarg (supplementary) 3-174
stccpy (supplementary) 3-175
stcd_i (supplementary) 3-176
stcd_l (supplementary) 3-177
stch_i (supplementary) 3-178
stci_d (supplementary) 3-179
stcis (supplementary) 3-180
stcisn (supplementary) 3-181
stclen (supplementary) 3-182
stcpm (supplementary) 3-182
Guardian TNS C Library Calls Reference Manual—128833
ix
3. Reference to Library Calls
stcpma (supplementary) 3-184
stcu_d (supplementary) 3-186
stpblk (supplementary) 3-187
stpbrk (supplementary) 3-188
stpchr (supplementary) 3-188
stpsym (supplementary) 3-189
stptok (supplementary) 3-191
strcat 3-192
strchr 3-193
strcmp 3-194
strcoll 3-195
strcpy 3-196
strcspn 3-197
strerror 3-198
strftime 3-199
strlen 3-201
strncat 3-202
strncmp 3-203
strncpy 3-205
strpbrk 3-206
strrchr 3-207
strspn 3-208
strstr 3-209
strtod 3-210
strtok 3-211
strtol 3-212
strtoul 3-214
strxfrm 3-215
stscmp (supplementary) 3-216
system 3-217
tan 3-218
tanh 3-219
terminate_program (supplementary)
time 3-222
tmpfile 3-223
tmpnam 3-223
toascii (supplementary) 3-224
tolower 3-225
toupper 3-226
x
Contents
3-220
128833 —Guardian TNS C Library Calls Reference Manual
Contents
trap_overflows (supplementary) 3-227
ungetc 3-228
unlink (supplementary) 3-229
va_arg 3-230
va_end 3-231
va_start 3-232
vfprintf 3-233
vprintf 3-234
vsprintf 3-235
wctomb 3-236
wcstombs 3-237
write (supplementary) 3-238
writeread (supplementary) 3-239
Index
Index-1
Tables
Table i.
Table ii.
Table 2-1.
Guardian Environment Manuals xiv
Open System Services Environment Manuals
Macros in Errnoh Header 2-2
Guardian TNS C Library Calls Reference Manual—128833
xiv
xi
Contents
xii
128833 —Guardian TNS C Library Calls Reference Manual
About This Manual
This manual describes the syntax and semantics of the Guardian TNS (Tandem NonStop
Series) C run-time library. The Guardian TNS C run-time library is available to TNS and
accelerated programs. This manual supports D40.00 or later releases of the Tandem
TNS C compiler and Guardian TNS C run-time library. Refer to previous editions of the
C Reference Manual if you are using a previous release. Refer to the Guardian TNS/R
Native C Library Calls Reference Manual for details on C library calls in TNS/R native
programs in the Guardian environment. Refer to the Open System Services Library Calls
Reference Manual for details on C library calls in the OSS environment.
Audience
This manual is intended for systems and applications programmers familiar with
Tandem NonStop systems, the Tandem NonStop Kernel, the Guardian API, and the
ISO/ANSI C language.
Organization of This Manual
The Guardian TNS C Library Calls Reference Manual is organized as follows:
•
•
•
Section 1, “Introduction to the Guardian TNS C Run-Time Library,” describes the
features of the Guardian TNS C run-time library.
Section 2, “Summary of Library Header Files,” summarizes the contents of the
headers that declare the functions, macros, types, and variables in the Guardian
TNS C run-time library.
Section 3, “Reference to Library Calls,” describes the functions in the Guardian
TNS C run-time library. It presents the routines in alphabetical order.
Guardian TNS C Library Calls Reference Manual—128833
xiii
Additional Information
About This Manual
Additional Information
Table i describes manuals that provide information about writing C programs for the
Guardian environment.
Table i. Guardian Environment Manuals
Manual
Description
C/C++ Programmer’s Guide
Describes the syntax and semantics of C. Provides
guidelines on writing C programs for Tandem NonStop
systems.
Common Run-Time Environment
(CRE) Programmer’s Guide
Explains how to use the CRE for running mixedlanguage programs written for D-series systems.
Guardian Procedure Calls
Reference Manual
Describes the syntax and programming considerations
for using system procedures.
Guardian Procedure Errors and
Messages Manual
Describes error codes, error lists, system messages, and
trap numbers for system procedures.
Table ii describes manuals that provide information about writing C programs for the
Open System Services (OSS) environment.
Table ii. Open System Services Environment Manuals
xiv
Manual
Description
Open System Services Library
Calls Reference Manual
Describes the syntax and semantics of C library calls for
the OSS environment.
Open System Services
Programmer’s Guide
Explains how to use the OSS application programming
interface of the operating system.
Open System Services System
Calls Reference Manual
Describes the syntax and programming considerations
for using OSS system calls.
128833 —Guardian TNS C Library Calls Reference Manual
About This Manual
Your Comments Invited
Your Comments Invited
After using this manual, please take a moment to send us your comments. You can do
this by returning a Reader Comment Card or by sending an Internet mail message.
A Reader Comment Card is located at the back of printed manuals and as a separate file
on the Tandem CD Read disc. You can either FAX or mail the card to us. The FAX
number and mailing address are provided on the card.
Also provided on the Reader Comment Card is an Internet mail address. When you send
an Internet mail message to us, we immediately acknowledge receipt of your message. A
detailed response to your message is sent as soon as possible. Be sure to include your
name, company name, address, and phone number in your message. If your comments
are specific to a particular manual, also include the part number and title of the manual.
Many of the improvements you see in Tandem manuals are a result of suggestions from
our customers. Please take this opportunity to help us improve future manuals.
Guardian TNS C Library Calls Reference Manual—128833
xv
Your Comments Invited
xvi
About This Manual
128833 —Guardian TNS C Library Calls Reference Manual
Notation Conventions
General Syntax Notation
The following list summarizes the notation conventions for syntax presentation in this
manual.
UPPERCASE LETTERS. Uppercase letters indicate keywords and reserved words; enter
these items exactly as shown. Items not enclosed in brackets are required. For example:
MAXATTACH
lowercase italic letters. Lowercase italic letters indicate variable items that you supply.
Items not enclosed in brackets are required. For example:
file-name
[ ] Brackets. Brackets enclose optional syntax items. For example:
TERM [\system-name.]$terminal-name
INT[ERRUPTS]
A group of items enclosed in brackets is a list from which you can choose one item or
none. The items in the list may be arranged either vertically, with aligned brackets on
each side of the list, or horizontally, enclosed in a pair of brackets and separated by
vertical lines. For example:
LIGHTS [ ON
]
[ OFF
]
[ SMOOTH [ num ] ]
K [ X | D ] address-1
{ } Braces. A group of items enclosed in braces is a list from which you are required to
choose one item. The items in the list may be arranged either vertically, with aligned
braces on each side of the list, or horizontally, enclosed in a pair of braces and separated
by vertical lines. For example:
LISTOPENS PROCESS { $appl-mgr-name }
{ $process-name }
ALLOWSU { ON | OFF }
| Vertical Line. A vertical line separates alternatives in a horizontal list that is enclosed in
brackets or braces. For example:
INSPECT { OFF | ON | SAVEABEND }
Guardian TNS C Library Calls Reference Manual—128833
xvii
General Syntax Notation
Notation Conventions
… Ellipsis. An ellipsis immediately following a pair of brackets or braces indicates that you
can repeat the enclosed sequence of syntax items any number of times. For example:
M address-1 [ , new-value ]...
[ - ] {0|1|2|3|4|5|6|7|8|9}...
An ellipsis immediately following a single syntax item indicates that you can repeat that
syntax item any number of times. For example:
"s-char..."
Punctuation. Parentheses, commas, semicolons, and other symbols not previously described
must be entered as shown. For example:
error := NEXTFILENAME ( file-name ) ;
LISTOPENS SU $process-name.#su-name
Quotation marks around a symbol such as a bracket or brace indicate the symbol is a
required character that you must enter as shown. For example:
"[" repetition-constant-list "]"
Item Spacing. Spaces shown between items are required unless one of the items is a
punctuation symbol such as a parenthesis or a comma. For example:
CALL STEPMOM ( process-id ) ;
If there is no space between two items, spaces are not permitted. In the following
example, there are no spaces permitted between the period and any other items:
$process-name.#su-name
Line Spacing. If the syntax of a command is too long to fit on a single line, each continuation
line is indented three spaces and is separated from the preceding line by a blank line.
This spacing distinguishes items in a continuation line from items in a vertical list of
selections. For example:
ALTER [ / OUT file-spec / ] CONTROLLER
[ , attribute-spec ]...
xviii
128833 —Guardian TNS C Library Calls Reference Manual
1
Intro
Run-Time Library
C is a relatively small, yet powerful and effective, programming language. With the
extensive run-time library C provides, C becomes an excellent language for a wide
variety of both systems and applications programming projects. For example, you can
use C to write:
•
•
•
•
•
•
System utilities
Interpreters, compilers, and other program-development tools
Servers for SCREEN COBOL and Pathsend requesters
Remote Server Call (RSC) requesters
Database applications using NonStop SQL/MP
Data communication managers, utilities, and applications
Tandem C conforms to the C language standard as set forth in ISO/IEC 9899:1990,
Programming Languages–C. (This is technically identical to ANSI C X3.159-1989,
Programming Language C.) Tandem includes several extensions to ISO standard C that
makes C an effective language for writing applications that run on Tandem NonStop
systems. These extensions include support for fault tolerant process pairs and systems
programming.
C programs compiled by the TNS C compiler and optionally processed by the
Accelerator program use the Guardian TNS C run-time library described in this manual.
Programs compiled with the TNS/R native C compiler use the Guardian TNS/R native C
run-time library. Refer to the Guardian TNS/R Native C Library Calls Reference Manual
for details.
Macros that are not in the library are expanded at preprocessing time.
The Guardian TNS C run-time library consists of the following parts:
CSMALL
The model-dependent version of the C run-time library for the
small-memory model (size of pointer and size of type int are 16 bits).
CLARGE
The model-dependent version of the C run-time library for the
large-memory model (size of pointer is 32 bits and size of type int is
16 bits).
CWIDE
The model-dependent version of the C run-time library for the
wide-data model (size of pointer and size of type int are 32 bits)
CNONSTOP The C fault tolerant programming functions for use with CLARGE
and CWIDE.
The Guardian TNS C run-time library also consists of the model-independent library,
CLIB. CLIB is part of system library. Tandem recommends that you do not bind CLIB
into your programs.
Guardian TNS C Library Calls Reference Manual—128833
1- 1
Introduction to the Guardian TNS C Run-Time
Library
One of the model-dependent libraries must be into your program, depending on the
memory or data model used. Refer to the C/C++ Programmer’s Guide for a complete
description on selecting the correct run-time library for your programs.
1- 2
128833 —Guardian TNS C Library Calls Reference Manual
2
Summary of Library Header Files
The macros and functions in the Guardian TNS C run-time library are declared in 20
header files. Each header contains declarations for a related set of library functions and
macros, as well as variables and types that complete that set. If you use a function in the
library, you should include the header file in which it is declared. Do not declare the
routine yourself because the declarations in the header files have provisions for several
situations that can affect the form of a given declaration, including:
•
•
•
•
Whether the routine is implemented internally as a function or a macro
Whether the function is written in a language other than C
Whether you are compiling for the small or large memory model
Whether you are compiling for the 16-bit or 32-bit (wide) data model
In addition, the header files use function prototypes to declare functions. These
prototype declarations enable the C compiler to check parameters and arguments for
compatibility, ensuring that calls to the library functions provide the correct number and
type of arguments.
A single set of C library header files support both the Guardian and Open System
Services (OSS) environments.
This section summarizes the contents of the 20 header files that declare the functions,
macros, types, and variables in the C run-time library. These header files are:
asserth
localeh
sqlh
talh
ctypeh
mathh
stdargh
timeh
errnoh
memoryh
stddefh
fcntlh
nonstoph
stdioh
floath
setjmph
stdlibh
limitsh
signalh
stringh
The header file cextdecs is described in the C/C++ Programmer’s Guide.
<asserth>
The header asserth defines the assert macro, which enables you to insert run-time
diagnostics in a program. After developing and debugging your program, you can
disable all the diagnostics by defining the identifier NDEBUG as a macro before
including asserth. When you do this, asserth defines assert as:
#define assert(ignore)
This effectively disables all diagnostics.
<ctypeh>
The header ctypeh declares routines that perform character testing and mapping
operations. These routines are:
isalnum
isdigit
isupper
isalpha
isgraph
isxdigit
isascii
islower
toascii
iscntrl
isprint
tolower
Guardian TNS C Library Calls Reference Manual—128833
iscsym
ispunct
toupper
iscsymf
isspace
2- 1
<errnoh>
Summary of Library Header Files
<errnoh>
The header errnoh declares one function and several object-like macros that are used by
several library functions to report errors. The function declared is errno, and returns a
value of type int. The ISO/ANSI C standard requires that the C run-time library return
only positive integral values to errno. Table 2-1 lists the macros and their symbolic
meanings.
Table 2-1. Macros in Errnoh Header (page 1 of 4)
2- 2
Macro
Meaning
E2BIG
Argument list too long
EACCES
Permission denied
EADDRINUSE
Address already in use
EADDRNOTAVAIL
Cannot assign requested address
EAFNOSUPPORT
Address family not supported
EAGAIN
No more processes
EALREADY
Operation already in progress
EBADCF
C file (code 180) not odd-unstructured
EBADDATA
Invalid data in buffer
EBADF
Bad file descriptor
EBADFILE
File type not supported
EBADMSG
An invalid message tag was found
EBADSYS
Invalid socket call
EBIGDIR
The positioning within an OSS directory failed because there
were more than 65535 file names beginning with the same two
characters in the directory
EBUSY
Mount device busy
ECHILD
No children
ECONNABORTED
Software caused connection abort
ECONNREFUSED
Connected refused
ECONNRESET
Connection reset by remote host
ECWDTOOLONG
The pathname of the current working directory is too long
EDEADLK
Deadlock condition
EDEFINEERR
An error exists in a Guardian DEFINE
EDESTADDRREQ
Destination address required
EDOM
Argument out of range
EEXIST
File already exists
EFAULT
Bad address
128833 —Guardian TNS C Library Calls Reference Manual
Summary of Library Header Files
<errnoh>
Table 2-1. Macros in Errnoh Header (page 2 of 4)
Macro
Meaning
EFBIG
File too large
EFILEBAD
Corrupt Guardian file or bad EDIT file structure
EFSBAD
Fileset catalog internal consistency error
EGUARDIANLOCKED
Guardian record or file locked
EGUARDIANOPEN
OSS unlink or rename function used on open Guardian file
EHAVEOOB
Out-of-band data available
EHDLSEM
An active semundo operation is active for an OSS process that is
attempting an exec-type function operation into another processor
EHOSTDOWN
Host is down
EHOSTUNREACH
No route to host
EIDRM
Identifier removed
EILSEQ
Illegal byte sequence
EINPROGRESS
Operation now in progress
EINTR
Interrupted system call
EINVAL
Invalid function argument
EIO
I/O error
EISCONN
Socket is already connected
EISDIR
Is a directory
EISGUARDIAN
OSS operation attempted on Guardian file descriptor
ELOOP
Too many symbolic links during pathname resolution
EMFILE
Maximum number of files already open
EMLINK
Too many links
EMSGSIZE
Message too long
ENAMETOOLONG
File name too long
ENETDOWN
Network is down
ENETRESET
Network dropped connection on reset
ENETUNREACH
Network is unreachable
ENFILE
File table overflow
ENOBUFS
No buffer space available
ENOCPU
CPU unavailable
ENOCRE
Non-CRE process requires CRE-dependent services
ENODATA
No data sent or received
ENODEV
No such device
Guardian TNS C Library Calls Reference Manual—128833
2- 3
<errnoh>
Summary of Library Header Files
Table 2-1. Macros in Errnoh Header (page 3 of 4)
2- 4
Macro
Meaning
ENOENT
No such file or directory
ENOERR
No error occurred
ENOEXEC
Exec format error
ENOIMEM
Insufficient internal memory
ENOLCK
No record locks available
ENOMEM
Insufficient user memory
ENOMSG
No message of desired type
ENONSTOP
NonStop C logic error
ENOPROTOOPT
Protocol not available
ENOREPLY
No reply in buffer
ENOROOT
Root fileset is not mounted
ENOSPC
No space left on device
ENOSYS
Function not implemented
ENOTCONN
Socket is not connected
ENOTDIR
Not a directory
ENOTEMPTY
Directory not empty
ENOTOSS
Not an OSS process
ENOTSOCK
Socket operation on non-socket
ENOTTY
Not a typewriter
ENXIO
No such device or address
EOPNOTSUPP
Operation not supported on socket
EOSSNOTRUNNING
Open System Services is not running or installed
EPARTIAL
Partial buffer received
EPERM
Not owner, permission denied
EPFNOSUPPORT
Protocol family not supported
EPIPE
Broken pipe or no reader on socket
EPROTONOSUPPORT
Protocol not supported
EPROTOTYPE
Protocol wrong type for socket
ERANGE
Value out of range
EROFS
Read only file system
ESHUTDOWN
Cannot send after socket shutdown
ESOCKTNOSUPPORT
Socket type not supported
128833 —Guardian TNS C Library Calls Reference Manual
Summary of Library Header Files
<fcntlh>
Table 2-1. Macros in Errnoh Header (page 4 of 4)
Macro
Meaning
ESPIERR
Interface error from SPI
ESPIPE
Illegal seek
ESRCH
No such process or table entry
ETIMEDOUT
Connection timed out
ETXTBSY
Object (text) file busy
EUNKNOWN
Unknown error
EVERSION
Version mismatch
EWOULDBLOCK
Operation would block
EXDEV
Cross-device link
EWRONGID
I/O operation on failed or downed IOP
EXDRDECODE
XDR decoding error
EXDRENCODE
XDR encoding error
<fcntlh>
The header fcntlh declares all of the alternate-model I/O functions and several of the
general file and model conversion functions. In addition, fcntlh defines several objectlike macros for use by the open, creat, lseek, edlseek, and fcntl functions.
The functions declared in fcntlh are:
chvol
fcntl
read
writeread
close
fdtogfn
readupdate
unlink
creat
lseek
reply
edlseek
open
write
Here are the macros defined for use in open and creat. The meanings of these macros are
described in the discussion of open in Section 3, “Reference to Library Calls”:
O_APPEND
O_EXCLUSIVE
O_SHARED
O_WRONLY
O_BINARY
O_PROTECTED
O_SYSMSG
O_CREAT
O_RDONLY
O_TEXT
O_EXCL
O_RDWR
O_TRUNC
Here are the macros defined for use in lseek and edlseek. The meanings of these macros
are described in the discussions of lseek and edlseek in Section 3, “Reference to Library
Calls”:
SEEK_CUR
SEEK_END
SEEK_SET
Guardian TNS C Library Calls Reference Manual—128833
2- 5
<floath>
Summary of Library Header Files
Here are the macros defined for use in fcntl. The meanings of these macros are
described in the discussion of fcntl in Section 3, “Reference to Library Calls”:
F_FLUSH
F_GETFN
F_SETFL
F_GETDTYPE
F_OFF
F_SETTAB
F_GETFCODE
F_ON
F_GETFL
F_SETBUF
Note. The fcntlh header is not specified by the ISO/ANSI C standard. The header is specified
by the POSIX.1 and XPG4 standards.
<floath>
The header floath defines object-like macros that describe the representation of floatingpoint numbers in the C language. The interpretation and significance of these macros are
described in the ISO/ANSI C standard.
Here are the macros that describe the floating-point type float. Following each macro
name is its defined value.
2- 6
FLT_DIG
6
FLT_EPSILON
2.7e-17
FLT_MANT_DIG
6
FLT_MAX
1.15792e77
FLT_MAX_10_EXP
77
FLT_MIN
8.63617e-78
FLT_MIN_10_EXP
(-77)
FLT_MIN_EXP
(-254)
FLT_MAX_EXP
(256)
FLT_RADIX
2
FLT_ROUNDS
1
128833 —Guardian TNS C Library Calls Reference Manual
Summary of Library Header Files
<floath>
Here are the macros that describe the floating-point type double. Following each macro
name is its defined value.
DBL_DIG
16
DBL_EPSILON
2.7e-17
DBL_MANT_DIG
16
DBL_MAX
1.1579208923716189e77
DBL_MAX_10_EXP
77
DBL_MIN
8.6361685550944446e-78
DBL_MIN_10_EXP
(-77)
DBL_MIN_EXP
(-254)
DBL_MAX_EXP
(256)
Here are the macros that describe the floating-point type long double. Following each
macro name is its defined value.
LDBL_DIG
16
LDBL_EPSILON
2.7e-17
LDBL_MANT_DIG
16
LDBL_MAX
1.1579208923716189e77
LDBL_MAX_10_EXP
77
LDBL_MIN
8.6361685550944446e-78
LDBL_MIN_10_EXP
(-77)
LDBL_MIN_EXP
(-254)
LDBL_MAX_EXP
(256)
Guardian TNS C Library Calls Reference Manual—128833
2- 7
<limitsh>
Summary of Library Header Files
<limitsh>
The header limitsh defines object-like macros that describe the representation and limits
of integral types in the C language.
Here are the macros that describe the integral types char, signed char, and unsigned char.
Each macro name is followed by its value and its meaning.
CHAR_BIT
8
Number of bits in a char variable
CHAR_MIN
0
Minimum char value
SCHAR_MIN
-128 Minimum signed char value
CHAR_MAX
255
Maximum char value
SCHAR_MAX
127
Maximum signed char value
UCHAR_MAX
255
Maximum unsigned char value
If you have not specified the wide-data model, these macros describe the integral types
int and unsigned int. Each macro name is followed by its value and its meaning.
INT_BIT
16
Number of bits in an int variable
INT_MIN
-32768 Minimum int value
INT_MAX
32767
Maximum int value
UINT_MAX
65535
Maximum unsigned int value
These macros describe the integral types int and unsigned int for the wide-data model.
INT_BIT
32
Number of bits in an int variable
INT_MIN
-2147483648 Minimum int value
INT_MAX
2147483647
Maximum int value
UINT_MAX
4294967295
Maximum unsigned int value
Here are the macros that describe the integral types long and unsigned long. Each macro
name is followed by its value and its meaning.
2- 8
LONG_BIT
32
Number of bits in a long variable
LONG_MIN
-2147483648 Minimum long value
LONG_MAX
2147483647
Maximum long value
ULONG_MAX
4294967295
Maximum unsigned long value
128833 —Guardian TNS C Library Calls Reference Manual
Summary of Library Header Files
<mathh>
Here are the macros that describe the integral types short and unsigned short. Each
macro name is followed by its value and its meaning.
SHRT_MIN
-32768 Minimum value for a short variable
SHRT_MAX
32767
Maximum short value
USHRT_MAX
65535
Maximum unsigned short value
Here are the macros that describe the integral type long long. Each macro name is
followed by its value and its meaning.
LLONG_BIT
64
Number of bits in a long long variable
LLONG_MIN
-9223372036854775807 Minimum long long value
LLONG_MAX
9223372036854775807
Maximum long long value
<localeh>
The header localeh declares the functions setlocale and localeconv. In addition, the
header contains the locale category macro and the lconv structure.
At any time, a C program has a current “locale” that is a collection of information that
describes the conventions appropriate to some environment, or to some nationality,
culture and language. The setlocale function is the interface to the program’s locale. The
setlocale function causes the program’s current locale to change to another specified
locale. The standard C locale is the only supported locale in the Guardian environment.
The locale category macro defines the standard locale categories that can be changed in
any given locale. The locale categories are described under the setlocale function in
Section 3, “Reference to Library Calls.”
The localeconv function returns a pointer to a structure of type lconv that contains
information useful for formatting numeric and monetary information. The lconv
structure is described under the localeconv function in Section 3, “Reference to Library
Calls.”
<mathh>
The header mathh declares several mathematical functions and defines one object-like
macro.
The mathematical functions are:
acos
cosh
ldexp
sinh
asin
exp
log
sqrt
atan
fabs
log10
tan
atan2
floor
modf
tanh
ceil
fmod
pow
cos
frexp
sin
The macro is HUGE_VAL. The mathematical functions return HUGE_VAL when an
overflow occurs.
Guardian TNS C Library Calls Reference Manual—128833
2- 9
<memoryh>
Summary of Library Header Files
<memoryh>
The header memoryh declares three memory-management functions:
movmem
repmem
setmem
<nonstoph>
The header nonstoph declares six functions that support fault tolerant programming in
C programs:
__ns_fget_file_state
__ns_fget_file_open_state
__ns_fopen_special
__ns_fset_file_state
__ns_backup_fopen
__ns_start_backup
The header also declares two structures:
__ns_std_io_file_open_state
__ns_std_io_file_state
The nonstoph header file is a Tandem extension. Refer to the Guardian Programmer’s
Guide for details on using these library calls for fault tolerant programming in C.
<setjmph>
The header setjmph declares the functions setjmp and longjmp, and the type jmp_buf.
Together, these entities enable you to bypass normal control flow and make nonlocal
jumps.
<signalh>
The header signalh declares the type sig_atomic_t, declares three functions, and defines
several macros for handling various “signals” that are exception conditions that are
generated by abnormal events.
The functions declared in signalh are:
signal
raise
_is_system_trap
The signal and raise functions are standard C functions. The _is_system_trap function is
a Tandem supplementary function. All three functions are described in Section 3,
“Reference to Library Calls.”
The standard C signal handlers that are defined as macros in signalh are:
SIG_DFL
SIG_IGN
SIG_ERR
The ISO/ANSI standard signals that are defined in signalh are:
SIGABRT
SIGINT
SIGTERM
SIGFPE
SIGILL
SIGSEGV
The Tandem defined signals that are defined in signalh are:
SIGSTK
SIGNOMEM
2- 10
SIGTIMEOUT
SIGMEMERR
SIGMEMMGR
SIGLIMIT
128833 —Guardian TNS C Library Calls Reference Manual
Summary of Library Header Files
<stdioh>
The signal handlers and signals are described in Section 3, “Reference to Library Calls,”
under the signal function.
<sqlh>
The header sqlh declares the functions dec_to_longlong and longlong_to_dec, which
convert data between representations as a decimal array and as a long long value.
<stdargh>
The header stdargh declares the type va_list and defines the function-like macros va_arg,
va_end, and va_start. Together, these entities enable a function to process a list of
arguments whose types and number are not known at compilation.
<stddefh>
The header stddefh defines the macro offsetof and declares the following types and
macros that are used by several library functions:
•
•
•
ptrdiff_t is the signed integral type that results when you subtract two pointers.
NULL is the object-like macro representing a null pointer value.
size_t is the unsigned integral type that results when you use the sizeof operator.
The offsetof macro is described in Section 3, “Reference to Library Calls.”
<stdioh>
The header stdioh declares one type and several functions and defines several object-like
macros; all of these routines perform ANSI-model I/O.
The functions declared in stdioh are:
clearerr
edfseek
fdopen
feof
fgetpos
fgets
fopen_std_file
fread
freopen
ftell
fwrite
perror
printf
remove
rename
setnbuf
setvbuf
tmpnam
ungetc
edftell
ferror
fileno
fprintf
fscanf
getc
putc
rewind
sprintf
vprintf
fclose
fflush
fopen
fputc
fseek
getchar
putchar
scanf
sscanf
vfprintf
fcloseall
fgetc
fputs
fsetpos
gets
puts
setbuf
tmpfile
vsprintf
The type declared is FILE, which contains all the information needed to control and
maintain a stream, including such indicators as the file position and the end of the file.
Guardian TNS C Library Calls Reference Manual—128833
2- 11
<stdlibh>
Summary of Library Header Files
The stdioh header also defines these object-like macros:
•
•
•
•
•
•
•
•
•
BUFSIZ specifies the size in bytes of the buffers the C language uses for streams.
Refer to the C/C++ Programmer’s Guide for the maximum length in bytes of these
buffers.
EOF is the value returned by several functions to indicate the end of the file.
FCHR_MAX specifies the maximum size (in bytes) of a file.
FILENAME_MAX specifies the maximum length (in characters) of a file name.
FOPEN_MAX specifies the maximum number of files that you can have open
simultaneously.
L_tmpnam specifies the minimum size (in characters) of a char array that can
accommodate a file name generated by tmpnam.
SEEK_END, SEEK_SET, and SEEK_CUR are used by edfseek and fseek.
stderr, stdin, and stdout denote the file pointers corresponding to the standard error,
input, and output files, respectively.
TMP_MAX specifies the maximum number of times you can call the tmpnam
function to acquire a unique file name.
<stdlibh>
The header stdlibh declares functions that perform a variety of operations, including
memory management, data conversion, and searching and sorting. These functions are:
abort
abs
atexit
atof
atoi
atol
bsearch
calloc
div
exit
free
get_assign_msg
get_assign_msg_by_name
get_max_assign_msg_ordinal
get_param_by_name
get_param_msg
get_startup_msg
getenv
heap_check
heap_check_always heap_min_block_size
labs
ldiv
malloc
_max
mblen
mbstows
mbtowc
_min
putenv
qsort
rand
realloc
srand
strtod
strtol
strtoul
system
terminate_program
trap_overflows
wcstombs
wctomb
The stdlibh header also declares two types, div_t and ldiv_t, that are used by the div and
ldiv functions. These types are described in the discussions of div and ldiv in Section 3,
“Reference to Library Calls.”
In addition, the stdlibh header defines the macros EXIT_FAILURE and
EXIT_SUCCESS for use in the exit function, and the macro RAND_MAX, which
specifies the maximum value returned by the rand function.
2- 12
128833 —Guardian TNS C Library Calls Reference Manual
Summary of Library Header Files
<timeh>
<stringh>
The header stringh declares these string-handling functions:
ecvt
memswap
stci_d
stcu_d
strcat
strlen
strspn
memchr
stcarg
stcis
stpblk
strchr
strncat
strstr
memcmp
stccpy
stcisn
stpbrk
strcmp
strncmp
strtok
memcpy
stcd_i
stclen
stpchr
strcpy
strncpy
stscmp
memmove
stcd_l
stcpm
stpsym
strcspn
strpbrk
memset
stch_i
stcpma
stptok
strerror
strrchr
<talh>
The header talh defines the three objectlike macros—CCE, CCG, and CCL—that denote
the condition-code states that a TAL function can return. Refer to the C/C++
Programmer’s Guide for information on how and when these macros are used.
<timeh>
The header timeh declares nine functions that deal with date, time, and the internal
clock. The header timeh also declares the CLOCKS_PER_SEC macro, two types
clock_t and time_t, and a structure type struct tm.
The CLOCKS_PER_SEC macro can be used to convert the value returned by the clock
function to seconds. The two types clock_t and time_t are arithmetic types capable of
representing time. Objects of type struct tm hold the components of a calendar time,
referred to as broken-down time.
The functions declared in timeh are:
asctime
difftime
mktime
clock
gmtime
strftime
ctime
localtime
time
The clock function determines how much processor time is used by a process up to the
point that the process invokes the clock function. The clock function returns the time in
microseconds; this value can be divided by CLOCKS_PER_SEC to convert it to
seconds.
In ISO/ANSI C, time comes in two principal versions: a “calendar time” expressed as an
integer, which represents the number of seconds that have elapsed since January 1, 1970,
and a “broken down time” expressed as a structure of type struct tm. The calendar time
is encoded with respect to Coordinated Universal Time (UTC). Use the time functions to
convert one version of time to the other. You can also print the time as a string.
Guardian TNS C Library Calls Reference Manual—128833
2- 13
<timeh>
2- 14
Summary of Library Header Files
128833 —Guardian TNS C Library Calls Reference Manual
3
Reference to Library Calls
This section describes the routines in the Guardian TNS C run-time library. The
description of each routine shows:
•
•
•
What the routine does
Whether the routine is a function or a macro
Whether the routine is part of standard C or is a supplementary Tandem extension to
the ISO/ANSI C standard.
•
•
•
•
What header or headers you need to include before calling the routine
What arguments the routine accepts and how it interprets them
What value the routine returns and how you should interpret it
What guidelines you need to remember when using the routine
Most of the descriptions also include an example that shows how to use the routine.
abort
The abort function causes abnormal termination, unless a signal handler catches
SIGABRT and does not return.
#include <stdlibh>
void abort(void);
abs
The abs function returns the absolute value of its argument.
#include <stdlibh>
int abs( int expr);
expr
is an expression whose value has type int.
Return Value
is the absolute value of expr.
Guardian TNS C Library Calls Reference Manual—128833
3- 1
acos
Reference to Library Calls
Usage Guidelines
•
The absolute value of the most negative integer (INT_MIN) cannot be represented.
Example
This example prints “The absolute value of -25 is 25.”
#include <stdioh>
#include <stdlibh>
int main(void)
{
int r, x;
x = -25;
r = abs(x);
printf("The absolute value of %d is %d.", x, r);
}
acos
The acos function computes the arc cosine of its argument.
#include <mathh>
double acos(double expr);
expr
is an expression of type double whose value is in the range -1 to +1.
Return Value
is the arc cosine of expr, expressed as a double value in the range 0 to pi radians. If
expr is not in the interval -1 to +1, acos returns the value zero and sets errno to
EDOM (a domain error).
Example
This example prints “The arc cosine is 0.000000.”
#include <mathh>
#include <stdioh>
int main(void)
{
double r, x;
x = 1.0;
r = acos(x);
printf("The arc cosine is %f.", r);
}
3- 2
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
asctime
asctime
The asctime function converts the broken-down time pointed to by timeptr into a string.
#include <timeh>
char *asctime (const struct tm *timeptr);
timeptr
points to the broken-down time.
Return Value
is a pointer to the string.
Usage Guidelines
•
The structure pointed to by timeptr is of type struct tm. The structure type struct tm
is defined in the header timeh and has the following members:
struct tm{
int tm_sec;
int tm_min;
int tm_hour;
int tm_mday;
int tm_mon;
int tm_year;
int tm_wday;
int tm_yday;
int tm_isdst;
};
/*
/*
/*
/*
/*
/*
/*
/*
/*
seconds after the minute: [0, 61]*/
minutes after the hour: [0, 59] */
hours since midnight: [0, 23]
*/
day of the month: [1, 31]
*/
months since January: [0, 11]
*/
years since 1900
*/
days since Sunday; [0, 6]
*/
days since January 1: [0, 365]
*/
Daylight Savings Time flag
*/
Note that the flag tm_isdst is positive if Daylight Savings Time is in effect, zero if it
is not, and negative if the information is not available.
•
The string containing the time has 26 characters and has the form:
Sun Sep 16 01:03:52 1973\n\0
The new-line character (\n) and null character(\0) occupy the last two positions in
the string.
•
Later calls to asctime() and ctime() overwrite the string.
Guardian TNS C Library Calls Reference Manual—128833
3- 3
asctime
Reference to Library Calls
Examples
1. This example converts the calendar time pointed to by &now to local time in the
form of a string.
#include <timeh>
#include <stdioh>
time_t now;
int main(void)
{
now = time(NULL);
printf("%s%s\n",
"asctime(localtime(&now)) = ", asctime(localtime(&now)));
}
2. This example shows two alternate methods for converting the calendar time to local
time in the form of a string.
#include <timeh>
#include <stdioh>
time_t now;
int main(void)
{
now = time(NULL);
printf("\n%s%s\n%s%s\n",
"
ctime(&now) = ", ctime(&now),
"asctime(localtime(&now)) = ", asctime(localtime(&now)));
}
Note that the following two function calls are equivalent:
asctime(localtime(&now)) and ctime(&now)
3- 4
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
asin
asin
The asin function computes the arc sine of its argument.
#include <mathh>
double asin(double expr);
expr
is an expression of type double whose value is in the range -1 to +1.
Return Value
is the arc sine of expr, expressed as a double value in the range -pi/2 to +pi/2
radians. If expr is not in the interval -1 to +1, asin returns the value zero and sets
errno to EDOM (a domain error).
Example
This example prints “The arc sine is 1.570796.”
#include <mathh>
#include <stdioh>
int main(void)
{
double r, x;
x = 1.0;
r = asin(x);
printf("The arc sine is %f.", r);
}
Guardian TNS C Library Calls Reference Manual—128833
3- 5
assert
Reference to Library Calls
assert
The assert macro enables you to insert run-time diagnostics, or assertions, into your
program. After developing and debugging your program, you can disable the assertions
by defining the identifier NDEBUG as a preprocessor symbol before including the
asserth header.
#include <asserth>
void assert(int expr);
expr
determines whether an invocation of assert generates a diagnostic message and
terminates the program. If expr evaluates to a nonzero value, assert does nothing and
program execution continues. If expr evaluates to zero, assert writes a diagnostic
message and stack trace to stderr, flushes and closes all files opened for ANSI or
alternate I/O, and calls the system procedure PROCESS_STOP_ with the ABEND
option.
Return Value
none.
Usage Guidelines
•
•
•
3- 6
The diagnostic message produced by assert includes the text of expr, the name of the
source file, and the source line number.
The expression you use as expr should not contain side effects, as these effects will
not occur if NDEBUG is defined.
To disable all assertions, you must ensure that NDEBUG is defined as a macro name
when asserth is included.
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
atan
atan
The atan function computes the arc tangent of its argument.
#include <mathh>
double atan(double expr);
expr
is an expression of type double.
Return Value
is the arc tangent of expr, expressed as a double value in the range -pi/2 to +pi/2
radians.
Example
This example prints “The arc tangent is 0.927295 radians.”
#include <stdioh>
#include <mathh>
int main(void)
{
double r, x, y, t;
x = 4.0;
y = 3.0;
t = x/y;
r = atan(t);
printf ("The arc tangent is %f radians.", r);
}
Guardian TNS C Library Calls Reference Manual—128833
3- 7
atan2
Reference to Library Calls
atan2
The atan2 function computes the arc tangent of the quotient of its arguments.
#include <mathh>
double atan2(double divid, double divis);
divid
is an expression of type double, specifying the dividend.
divis
is an expression of type double, specifying the divisor.
Return Value
is the arc tangent of (divid/divis), expressed as a double value in the range -pi to +pi
radians. If both arguments are zero, atan2 returns the value HUGE_VAL and sets
errno to EDOM (a domain error).
Example
This example prints “The arc tangent is .927295.”
#include <mathh>
#include <stdioh>
int main(void)
{
double y, x, r;
y = 4.0;
x = 3.0;
r = atan2(y,x);
printf("The arc tangent is %f.", r);
}
3- 8
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
atexit
atexit
The atexit function registers a function for the run-time library to call at normal program
termination.
#include <stdlibh>
int atexit(void (*function)(void));
function(void)
points to the function you want to register for execution at normal program
termination.
Return Value
is zero if atexit successfully registers the function; otherwise, atexit returns a
nonzero value.
Usage Guidelines
•
•
•
•
•
Several constraints apply to a function you register:
The function cannot return a value.
The function cannot require parameters.
The function cannot call exit or atexit.
You can use atexit to register up to 32 functions for the run-time library to call at
normal program termination.
Guardian TNS C Library Calls Reference Manual—128833
3- 9
atof
Reference to Library Calls
atof
The atof function converts a string to a value of type double.
#include <stdlibh>
double atof(const char *str_ptr);
str_ptr
points to the string to convert.
Return Value
is the floating-point value of the string *str_ptr, expressed as a double value. atof
returns a value of zero if the first nonspace character in *str_ptr is not a sign, a
decimal digit, or a decimal point.
Usage Guidelines
•
The atof function begins the conversion by skipping any leading space characters (as
defined by the isspace function) in *str_ptr. It then scans for a valid floating-point
constant, continuing until it encounters an invalid character or the null character
terminating the string.
Example
This example converts the string “1.34” to a floating-point number:
#include <stdlibh>
int main(void)
{
char *string;
double num;
string = "1.34";
num = atof(string);
}
3- 10
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
atoi
atoi
The atoi function converts a string to a value of type int.
#include <stdlibh>
int atoi(const char *str_ptr);
str_ptr
points to the string to convert.
Return Value
is the numeric value of the string *str_ptr, expressed as an int value, atoi returns a
value of zero if the first nonspace character in *str_ptr is not a sign or a decimal
digit.
Usage Guidelines
•
The atoi function begins the conversion by skipping any leading space characters (as
defined by the isspace function) in *str_ptr. It then scans for a valid int constant,
continuing until it encounters an invalid character or the null character terminating
the string.
Example
This example converts the string “123” to an integer:
#include <stdlibh>
#include <stdioh>
int main(void)
{
int i;
char *string;
string = "
123";
i = atoi(string);
printf("%d\n",i); /* prints "123" */
}
Guardian TNS C Library Calls Reference Manual—128833
3- 11
atol
Reference to Library Calls
atol
The atol function converts a string to a value of type long.
#include <stdlibh>
long atol( const char *str_ptr);
str_ptr
points to the string to convert.
Return Value
is the numeric value of the string *str_ptr, expressed as a long value, atol returns a
value of zero if the first nonspace character in *str_ptr is not a sign or a decimal
digit.
Usage Guidelines
•
The atol function begins the conversion by skipping any leading space characters (as
defined by the isspace function) in *str_ptr. It then scans for a valid long constant,
continuing until it encounters an invalid character or the null character terminating
the string.
Example
This example converts the string “1234567” to a long integer:
#include <stdlibh>
#include <stdioh>
int main(void)
{
long i;
char *string;
string = "1234567";
i = atol(string);
printf("%ld\n",i); /* prints "1234567" */
}
3- 12
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
bsearch
bsearch
The bsearch function searches an array of elements for an element matching a specified
value.
#include <stdlibh>
void *bsearch(const void *key, const void *base, size_t nmemb,
size_t size, int (*compar)(const void *, const void *));
key
points to the value to match.
base
points to the first element in the array.
nmemb
specifies the number of elements in the array.
size
specifies the size in bytes of each element.
compar(void *, void *)
points to a function that compares two elements of size size, returning an integer less
than, equal to, or greater than zero if its first argument is respectively less than,
equal to, or greater than its second argument.
Return Value
points to the matching element of the array if a match is found; otherwise, bsearch
returns the pointer value NULL.
Usage Guidelines
•
•
Before you can use bsearch, the elements of the array being searched must be sorted
in ascending order, according to the function pointed to by compar. You can sort
them using the qsort library function.
The bsearch function uses a binary, not sequential, searching algorithm.
Consequently, if two or more elements of the array are equal to *key, then bsearch
does not necessarily return the sequentially first of them as the match.
Guardian TNS C Library Calls Reference Manual—128833
3- 13
calloc
Reference to Library Calls
calloc
The calloc function allocates memory for an array of elements and sets the allocated
memory to zeros.
#include <stdlibh>
void *calloc(size_t num_elts, size_t size_of_elt);
num_elts
specifies the number of elements in the array.
size_of_elt
specifies the size in bytes of a single element of the array.
Return Value
points to the allocated array, expressed as a pointer to void. If an error occurs, calloc
returns the pointer value NULL.
Usage Guidelines
•
•
•
The calloc function allocates memory starting on a word boundary.
Note that calloc returns a pointer to void, which is compatible with any pointer type.
However, if you explicitly specify the intended type using a cast expression, your
code will be more maintainable and readable. The following examples show the
intended type using a cast expression.
If you have compiled your program for the large-memory model, the calloc function
will automatically enlarge the extended data segment when necessary.
Examples
1. This example allocates memory for an array of 25 elements that are two bytes each:
#include <stdlibh>
char *array_ptr;
size_t nelt;
size_t sizelt;
nelt = 25;
sizelt = 2;
array_ptr = (char *)calloc(nelt, sizelt);
3- 14
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
ceil
2. This example allocates memory for a structure of 20 elements that are each the size
of the structure name:
#include <stdlibh>
int main(void)
{
struct name
{
char *last;
char *first;
} *s_ptr;
s_ptr = (struct name *)calloc(20, sizeof(struct name));
}
ceil
The ceil function returns the smallest integer not less than the value of its argument.
#include <mathh>
double ceil(double expr);
expr
is an expression of type double.
Return Value
is the smallest integer not less than expr, expressed as a double value.
Example
This example prints “The ceiling value of 1.090000 is 2.000000.”
#include <mathh>
#include <stdioh>
int main(void)
{
double x, r;
x = 1.09;
r = ceil(x);
printf("The ceiling value of %f is %f.", x, r);
}
Guardian TNS C Library Calls Reference Manual—128833
3- 15
chvol (supplementary)
Reference to Library Calls
chvol (supplementary)
The chvol function changes the default volume and subvolume names used to qualify
partial file names.
#include <fcntlh>
short chvol(char *volume);
volume
points to a string containing a valid volume and subvolume name.
Return Value
is zero if the operation is successful, or -1 if an error occurs.
Usage Guidelines
•
•
The run-time library expands all partial file names using the default volume and
subvolume names. To find out what the initial defaults are, use the getevn function.
If you include a file name in addition to the volume and subvolume names, the chvol
function ignores it.
Example
This example changes the default volume and subvolume names to $rock and music,
respectively:
#include <fcntlh>
chvol("$rock.music");
3- 16
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
clearerr
clearerr
The clearerr function resets the end-of-file and error indicators of a file opened for
ANSI I/O.
#include <stdioh>
void clearerr(FILE *stream);
stream
denotes a file opened for ANSI I/O.
Return Value
none.
Usage Guidelines
•
•
The clearerr function might be implemented as a macro in a future release.
The end-of-file and error indicators are reset only when you open the file or
explicitly call the clearerr, edfseek, fseek, or rewind function.
Example
This example resets the end-of-file and error indicators for the file $a.b.c:
#include <stdioh>
FILE *fp;
fp = fopen("$a.b.c", "r+");
/* ... */
clearerr(fp);
Guardian TNS C Library Calls Reference Manual—128833
3- 17
clock
Reference to Library Calls
clock
The clock function determines how much processor time is used by the calling process
up to the point that the process invokes the clock function.
#include <timeh>
clock_t clock(void);
Return Value
is the process execution time of the CPU for this process. The time is given in
microseconds.
Usage Guidelines
•
3- 18
The clock function returns the time in microseconds. This returned value can be
divided by CLOCKS_PER_SEC to convert it to seconds. The CLOCKS_PER_SEC
macro is defined in the header timeh.
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
close (supplementary)
close (supplementary)
The close function closes a file opened for alternate I/O.
#include <fcntlh>
int close(int file_des);
file_des
is the descriptor denoting a file opened for alternate I/O.
Return Value
is zero if the operation is successful, or -1 if an error occurs.
Usage Guidelines
•
You must call the close function when you finish using a file.
Example
This example closes the file $a.b.c:
#include <fcntlh>
int status;
int filedes;
filedes = open("$a.b.c", 0_RDWR);
/* ... */
status = close(filedes);
if(status != 0) printf("Close of $a.b.c failed.");
Guardian TNS C Library Calls Reference Manual—128833
3- 19
cos
Reference to Library Calls
cos
The cos function computes the cosine of its argument.
#include <mathh>
double cos(double expr);
expr
is an expression of type double, specifying an angle in radians.
Return Value
is the cosine of expr, expressed as a double value.
Example
This example prints “The cosine is 0.540302.”
#include <mathh>
#include <stdioh>
int main(void)
{
double r, x;
x = -1.0;
r = cos(x);
printf ("The cosine is %f.", r);
}
3- 20
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
creat (supplementary)
cosh
The cosh function computes the hyperbolic cosine of its argument.
#include <mathh>
double cosh(double expr);
expr
is an expression of type double.
Return Value
is the hyperbolic cosine of expr, expressed as a double value. If the computation
causes an overflow, cosh returns the value HUGE_VAL.
Usage Guidelines
•
If expr has too great a magnitude, cosh sets errno to ERANGE (a range error).
Example
This example prints “The hyperbolic cosine is 1.543081.”
#include <mathh>
#include <stdioh>
int main(void)
{
double r, x;
x = -1.0;
r = cosh(x);
printf ("The hyperbolic cosine is %f.", r);
}
creat (supplementary)
The creat function creates a new C binary file or erases all data from an existing C
binary file and then opens the file for alternate I/O and write-only access.
#include <fcntlh>
int creat(char *fname, [int security], [int pext],
[int sext]);
fname
points to a string containing a valid file name.
Guardian TNS C Library Calls Reference Manual—128833
3- 21
ctime
Reference to Library Calls
security
specifies the security setting. See the FUP SECURE command description of integer
encoding in the FUP Reference Manual for more information.
pext
specifies the number of pages (2048-byte blocks) in the primary extent; it must be in
the range 1 through 65,535. If you omit pext, then creat uses the value 2.
sext
specifies the number of pages in each of the secondary extents; it must be in the
range 1 through 65,535. If you omit sext, then creat uses the value 16.
Return Value
is the descriptor denoting the file if the operation is successful; otherwise creat
returns the value -1.
Usage Guidelines
•
The creat function creates C binary files (code 180) only. To create an Edit file, use
the open function with the O_TEXT and O_CREAT flags.
•
•
The creat function ignores security, pext, and sext for files that already exist.
Use the creat function only on files that you plan to rewrite completely. Any existing
data is lost.
•
For more information regarding file extents and pages, refer to the ENSCRIBE
Programmer’s Guide.
•
The default number of maxextents for files created by creat is 500.
Example
This example creates a file named $a.b.c:
#include <fcntlh>
int filedes;
filedes = creat("$a.b.c");
ctime
The ctime function converts the calendar time pointed to by timer to local time in the
form of a string.
#include <timeh>
char *ctime(const time_t *timer);
3- 22
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
ctime
timer
points to the calendar time.
Return Value
is a pointer to the string.
Usage Guidelines
•
The ctime function is equivalent to:
asctime(localtime(*timer));
•
Later calls to asctime and ctime overwrite the string. Refer to “asctime” on page 3-3
for more details.
Examples
1. This example converts the calendar time pointed to by &now to local time in the
form of a string.
#include <timeh>
#include <stdioh>
time_t now;
int main(void)
{
now = time(NULL);
printf("\n%s%s\n", "ctime(&now) = ", ctime(&now));
}
2. This example shows two alternate methods for converting the calendar time to local
time in the form of a string. Note that ctime(&now) and asctime(localtime(&now))
are equivalent function calls.
#include <timeh>
#include <stdioh>
time_t now;
int main(void)
{
now = time(NULL);
printf("\n%s%s\n%s%s\n",
"
ctime(&now) = ", ctime(&now),
"asctime(localtime(&now)) = ", asctime(localtime(&now)));
}
Guardian TNS C Library Calls Reference Manual—128833
3- 23
dec_to_longlong (supplementary)
Reference to Library Calls
dec_to_longlong (supplementary)
The dec_to_longlong function converts the SQL DECIMAL value stored in a C array of
decimal to a C long long value.
#include <sqlh>
int dec_to_longlong(decimal *dec_ary, int chr_count,
long long *ll_val);
dec_ary
points to the first character of the decimal array that contains the SQL DECIMAL
value to convert.
chr_count
specifies the number of valid DECIMAL characters in *dec_ary.
ll_val
points to the variable of type long long where dec_to_longlong stores the converted
DECIMAL value.
Return Value
is zero if the conversion is successful; otherwise, dec_to_longlong returns one of
these status codes:
1
Indicates that significant digits of the DECIMAL value were truncated in the
conversion; that is, the converted value exceeded the bounds of a long long
value.
2
Indicates that the chr_count argument had an invalid value.
3
Indicates that *dec_ary contained characters that are not valid in SQL
DECIMAL values.
Usage Guidelines
•
•
3- 24
When dec_to_longlong returns a nonzero value to indicate that the conversion was
not successful, the value stored in *ll_val is undefined.
For more information regarding the representation of SQL DECIMAL values in
C arrays of decimal, refer to the NonStop SQL Programming Manual for C.
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
div
difftime
The difftime function computes the difference between two calendar times:
time1 - time2.
#include <timeh>
double difftime(time_t time1, time_t time2);
time1
specifies a calendar time, and is of type type_t. Type type_t is defined in the header
timeh.
time2
specifies another calendar time, and is also of type type_t.
Return Value
is the difference time1 - time2. The difference is expressed in seconds as a floatingpoint number of type double.
div
The div function computes the int quotient and int remainder that result from the integral
division of its two int arguments.
#include <stdlibh>
div_t div(int dividend, int divisor);
dividend
specifies the dividend, or numerator, of the integral division equation.
divisor
specifies the divisor, or denominator, of the integral division equation.
Return Value
is a structure of type div_t, which comprises two int members, quot and rem, that
respectively contain the quotient and remainder resulting from the integral division
of dividend by divisor.
Guardian TNS C Library Calls Reference Manual—128833
3- 25
ecvt (supplementary)
Reference to Library Calls
ecvt (supplementary)
The ecvt function converts a numeric value to a string.
#include <stdlibh>
char *ecvt(double value, short ndig, short *dec, short *sign);
value
is the value to convert.
ndig
is the number of digits in the converted string. Because the converted string does not
include a sign or a decimal point, ndig does not include them in its count of digits.
dec
points to the variable of type int where ecvt stores the position of the decimal point
relative to the beginning of the string. A negative value indicates that the decimal
point is to the left of the first digit.
sign
points to the variable of type int where ecvt stores the sign. A nonzero value
indicates a negative result; the value zero indicates a positive result.
Return Value
is a pointer to the converted string.
Usage Guidelines
•
•
3- 26
*dec indicates where in the return string the decimal point should appear. The string
itself does not include the decimal-point character.
The ecvt function returns a pointer to static data within the function. Consequently,
the content of the returned string changes with each call to ecvt.
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
edfseek (supplementary)
Example
This example prints “num = -123.45670”:
#include <stdlibh>
#include <stdioh>
int main(void)
{
double num;
int dp;
int sign;
char *string;
int i;
num = -123.4567;
string = ecvt(num, 8, &dp, &sign);
printf("num = ");
if(sign != 0)
printf("-");
/* print integer part of number */
for(i=0;i<dp;i++)
printf("%c", string[i]);
/* print decimal point and fractional part of number */
printf(".");
for(i=dp;i<8;i++)
printf("%c", string[i]);
printf("\n");
}
edfseek (supplementary)
The edfseek function sets the file-position indicator of an Edit file opened for ANSI I/O
to the beginning of a specified line.
#include <stdioh>
int edfseek(FILE *stream, long pos, int pos_base);
stream
denotes an Edit file opened for ANSI I/O.
pos
specifies the desired file position. Depending on pos_base, the file position is either
a line number or a line offset.
Guardian TNS C Library Calls Reference Manual—128833
3- 27
edfseek (supplementary)
Reference to Library Calls
pos_base
is one of the following alternatives:
•
•
•
SEEK_SET indicates that pos is a line number. The file is positioned at the first line
whose line number is greater than or equal to the line number requested.
SEEK_CUR indicates that pos is the number of lines from the file-position
indicator; pos can be positive or negative.
SEEK_END indicates that pos is the number of lines from the end of the file; pos
can be either zero or negative. If zero, the file is positioned at the next line to be
written–that is, at the end of the file. If negative, pos specifies how many lines to
skip backwards.
Return Value
is zero if the operation is successful; otherwise, edfseek returns EOF and sets errno
to the Guardian error number.
Usage Guidelines
•
•
•
•
•
•
3- 28
The edfseek function resets the end-of-file and error indicators.
If you specify a line beyond the last line in the file, the file is positioned at the
beginning of the next line to be written to the file.
If you specify a line before the first line in the file, the file is positioned at the
beginning of the first line.
Line numbers are numeric labels that are sorted in numeric order. Because they are
not sequence numbers, a requested line number might not be in the file. This is not
an error, and the line number (the next higher line number in the file), rather than -1,
is returned.
Relative positioning (using pos_base values SEEK_CUR or SEEK_END) is slower
than absolute positioning (using pos_base value SEEK_SET) because it requires
sequential scanning of the file.
For absolute positioning (using pos_base value SEEK_SET), pos is the Edit line
number multiplied by 1000. For example, 23000L corresponds to line 23, and
44120L corresponds to line 44.12.
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
edftell (supplementary)
edftell (supplementary)
The edftell function retrieves the file-position indicator of an Edit file opened for
ANSI I/O.
#include <stdioh>
long edftell(FILE *stream);
stream
denotes an Edit file opened for ANSI I/O.
Return Value
is the file-position indicator of the Edit file, expressed as a long value. This value is
the Edit line number multiplied by 1000. For example, 23000L corresponds to
line 23, and 44120L corresponds to line 44.12.
Guardian TNS C Library Calls Reference Manual—128833
3- 29
edlseek (supplementary)
Reference to Library Calls
edlseek (supplementary)
The edlseek function sets the file-position indicator of an Edit file opened for
alternate I/O to the beginning of the line that you request.
#include <fcntlh>
long edlseek(short file_des, long pos, short pos_base);
file_des
is the descriptor denoting an Edit file opened for alternate I/O.
pos
specifies the desired file position. Depending on pos_base, the file position is either
a line number or a line offset.
pos_base
is one of the following alternatives:
•
•
•
SEEK_SET indicates that pos is a line number. The file is positioned at the first line
whose line number is greater than or equal to the line number requested.
SEEK_CUR indicates that pos is the number of lines from the file-position
indicator; pos can be positive or negative.
SEEK_END indicates that pos is the number of lines from the end of the file; pos
can be either zero or negative. If pos is zero, the file is positioned at the next line to
be written–that is, at the end of the file. If it is negative, pos specifies how many
lines to skip backwards.
Return Value
is the line number if the operation is successful; otherwise, edlseek returns the
value -1 and sets errno to the Guardian error number.
Usage Guidelines
•
•
•
•
3- 30
The edlseek function resets the end-of-file and error indicators.
If you specify a line beyond the last line in the file, the file is positioned at the
beginning of the next line to be written to the file. If you specify a line before the
first line in the file, the file is positioned at the beginning of the first line.
Relative positioning (using pos_base values SEEK_CUR or SEEK_END) is slower
than absolute positioning (using pos_base value SEEK_SET) because it requires
sequential scanning of the file.
For absolute positioning (using pos_base value SEEK_SET), pos is the Edit line
number multiplied by 1000. For example, 23000L corresponds to line 23, and
44120L corresponds to line 44.12.
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
exit
exit
The exit function writes to open files any data left in the buffers, closes files, and
terminates execution of your C program.
#include <stdlibh>
void exit(int status);
status
specifies the termination alternatives:
•
•
•
If the status value is zero, the compiler translates it to EXIT_SUCCESS which
indicates normal termination.
If the status value is less than zero, the compiler translates it to EXIT_FAILURE
which indicates abnormal termination.
If the status value is greater than zero, the compiler equates a completion code to
status.
Return Value
none; exit does not return to its caller.
Usage Guidelines
•
•
•
•
•
When you use EXIT_FAILURE, your program terminates with a completion code
of 5. When you use EXIT_SUCCESS, it terminates with a completion code of 0.
A completion code of 5 indicates abnormal, voluntary, but premature termination
with FATAL errors or diagnostics. For example, if the process is a compiler, the
compilation terminated with FATAL diagnostics, with an incomplete object file
being built and an incomplete listing generated (the compiler quit compiling
prematurely).
A completion code of 0 indicates normal, voluntary termination with no errors.
For active backup process pairs, if the primary process calls exit and specifies
normal termination (the status value is zero), both the primary and backup processes
terminate.
For more information regarding completion codes, refer to the Guardian Procedure
Calls Reference Manual.
Guardian TNS C Library Calls Reference Manual—128833
3- 31
exp
Reference to Library Calls
exp
The exp function computes the exponential function (base e) of its argument.
#include <mathh>
double exp(double expr);
expr
is an expression of type double, specifying the power to which e is raised.
Return Value
is the exponential (e raised to the power) of expr, expressed as a double value. If the
computation causes an overflow or underflow, exp returns the value HUGE_VAL or
the value zero, respectively. In these cases, exp also sets errno to ERANGE (a range
error).
Example
This example prints “e raised to the power 1 is 2.718282.”
#include <mathh>
#include <stdioh>
int main(void)
{
double r, x;
x = 1.0;
r = exp(x);
printf("e raised to the power 1 is %f.", r);
}
3- 32
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
fabs
fabs
The fabs function computes the absolute value of its floating-point argument.
#include <mathh>
double fabs(double expr);
expr
is an expression of type double.
Return Value
is the absolute value of expr, expressed as a double value.
Example
This example prints “The absolute value of -25.000000 is 25.000000.”
#include <mathh>
#include <stdioh>
int main(void)
{
double x, r;
x = -25;
r = fabs(x);
printf("The absolute value of %f is %f.", x, r);
}
Guardian TNS C Library Calls Reference Manual—128833
3- 33
fclose
Reference to Library Calls
fclose
The fclose function closes a file opened for ANSI I/O and writes any data in the buffer
to the file.
#include <stdioh>
int fclose(FILE *stream);
stream
denotes a file opened for ANSI I/O.
Return Value
is zero if the operation is successful or the value EOF if an error occurs.
Usage Guidelines
•
•
If the file was written to, fclose writes any data in the buffer to the file.
Whenever a program calls the exit function or returns from main, C automatically
closes all open files. You should, however, close all files explicitly by calling fclose
or fcloseall.
Example
This example closes the file $a.b.c:
#include <stdioh>
int main(void)
{
FILE *fp;
int status;
fp = fopen("$a.b.c", "w");
/* ... */
status = fclose(fp);
if(status==EOF) printf("fclose function failed\n");
}
3- 34
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
fcntl (supplementary)
fcloseall (supplementary)
The fcloseall function closes all files opened for ANSI I/O and alternate I/O, including
stdin, stdout, and stderr.
#include <stdioh>
void fcloseall(void);
Usage Guidelines
•
•
If one of the files was written to, fcloseall writes any data in the buffer to the file.
Whenever a program calls the exit function or returns from main, C closes all open
files automatically. You should, however, close all files explicitly by calling fclose or
fcloseall.
fcntl (supplementary)
The fcntl function provides a number of file control-operations. By specifying the
command argument, you select a file-control operation.
#include <fcntlh>
int fcntl(int file_des, int command [, int option]);
file_des
is the descriptor denoting a file opened for alternate I/O.
command
is one of the command constants listed under “Usage Guidelines.” These constants
are object-like macros defined in the fcntlh header.
option
is, depending on the command, one of the following:
•
•
A flag word whose attribute bits are represented by object-like macros defined in the
header fcntlh. See the open function for a description of these macros.
An on or off indicator represented by the object-like macros F_ON or F_ON,
defined in the header fcntlh.
Guardian TNS C Library Calls Reference Manual—128833
3- 35
fcntl (supplementary)
Reference to Library Calls
Return Value
depends upon command:
•
•
•
•
For F_GETFL, fcntl returns the file open-option flags.
For F_GETDTYPE, fcntl returns the device type of the file.
For F_GETFCODE, fcntl returns the file code if the file is a disk file, or -1 if it
is not.
For all others, fcntl returns 1 if the operation is successful, or -1 if an error occurs.
Usage Guidelines
•
The commands provided by fcntl are:
Command
F_FLUSH*
Option
Operation
none
Flushes buffered output.
F_SETTAB*
F_SETBUF*
F_ON / F_OFF
Turns tab expansion on or off.
F_ON / F_OFF
Turns terminal output buffering on or off.
F_GETFL
none
Returns the file’s open-option flags.
F_SETFL
flags
Sets the file’s open-option flags.
F_GETDTYPE*
F_GETFCODE*
none
Returns the file’s device type.
none
Returns the file code for a disk file; otherwise,
returns -1.
F_GETFN*
none
Returns the file number.
* indicates that the command is a Tandem extension to the ISO C Standard.
3- 36
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
fdopen (supplementary)
fdopen (supplementary)
The fdopen function opens a file for ANSI I/O that was opened for alternate I/O.
#include <stdioh>
FILE *fdopen(int file_des, char *access);
file_des
is the descriptor denoting a file opened for alternate I/O.
access
points to a string that specifies how you want to access the new file. Refer to
“fopen” on page 3-48 for the possible values of *access.
Return Value
is a pointer to FILE if the operation is successful; otherwise, fdopen returns the
pointer value NULL.
Usage Guidelines
•
If *access is incompatible with the type of access that the file had on entry to
fdopen, then fdopen returns the pointer value NULL, which indicates failure.
Guardian TNS C Library Calls Reference Manual—128833
3- 37
fdtogfn (supplementary)
Reference to Library Calls
fdtogfn (supplementary)
The fdtogfn function retrieves the file number of a file opened for alternate I/O.
#include <fcntlh>
short fdtogfn(short file_des);
file_des
is the descriptor denoting a file opened for alternate I/O.
Return Value
is the Guardian file number of the file or -1 if file_des does not represent an open
file.
Example
This example returns the file number of the file $a.b.c:
#include <fcntlh>
short filedes;
short filenum;
filedes = open("$a.b.c", O_RDWR);
/* ... */
filenum = fdtogfn(filedes);
3- 38
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
feof
feof
The feof function checks whether the file-position indicator of a file opened for
ANSI I/O is at the end of the file.
#include <stdioh>
int feof(FILE *stream);
stream
denotes a file opened for ANSI I/O.
Return Value
is nonzero if the file-position indicator is at the end of the file; otherwise, feof
returns a zero.
Usage Guidelines
•
The feof function might be implemented as a macro in a future release.
Example
This example checks the end-of-file indicator for the file $a.b.c:
#include <stdioh>
FILE *fp;
fp = fopen("$a.b.c", "r");
/* ... */
if(feof(fp)) printf("End of file has been reached.");
Guardian TNS C Library Calls Reference Manual—128833
3- 39
ferror
Reference to Library Calls
ferror
The ferror function checks the error indicator of a file opened for ANSI I/O.
#include <stdioh>
int ferror(FILE *stream);
stream
denotes a file opened for ANSI I/O.
Return Value
is nonzero if an error occurred when reading or writing the file; otherwise, ferror
returns a zero.
Usage Guidelines
•
•
•
•
•
The ferror function might be implemented as a macro in a future release.
The error indicator remains set until one of the following events occurs:
The file is closed.
You call the clearerr function, which specifically clears the error indicator.
You call the fseek or edfseek function.
Example
This example checks the error indicator for the file $a.b.c:
#include <stdioh>
int status;
FILE *fp;
fp = fopen("$a.b.c", "r+");
/* ... */
status = ferror(fp);
if(status != 0)
printf("An error occurred reading or writing the file.");
3- 40
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
fflush
fflush
The fflush function writes to disk any data that is in the buffer of a file opened for
ANSI I/O.
#include <stdioh>
int fflush(FILE *stream);
stream
denotes a file opened for ANSI I/O.
Return Value
is zero if the operation is successful or nonzero if an error occurs.
Usage Guidelines
•
•
If you pass NULL as the argument to fflush, the C compiler flushes all files
currently opened for ANSI I/O.
In C-series releases, the fflush function can flush partial lines if stdout and stderr are
directed to type 101 Edit files. In D-series releases, the fflush function does not flush
partial lines if stdout and stderr are directed to type 101 Edit tiles because these files
are shared resources under the CRE.
In D-series releases, to flush partial lines to the stdout and stderr files, you must
either open the files using freopen or close and reopen the files using fopen. In both
cases, these files cannot be shared.
Example
This example writes all buffered data for the file $a.b.c to disk:
#include <stdioh>
FILE *fp;
fp = fopen("$a.b.c", "a");
/* ... */
fflush(fp);
Guardian TNS C Library Calls Reference Manual—128833
3- 41
fgetc
Reference to Library Calls
fgetc
The fgetc function retrieves the next character from a file opened for ANSI I/O.
#include <stdioh>
int fgetc(FILE *stream);
stream
denotes a file opened for ANSI I/O.
Return Value
is the character retrieved from the file. If fgetc encounters the end of the file or an
error, it returns the value EOF. To distinguish between these two cases, use the feof
or ferror function.
Example
This example returns the next character from the file $a.b.c:
#include <stdioh>
int c;
FILE *fp;
fp = fopen("$a.b.c", "r");
/* ... */
c = fgetc(fp);
3- 42
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
fgetpos
fgetpos
The fgetpos function gets the current value of the file-position indicator for the file
associated with stream and stores it in the variable pointed to by pos. The stored value
can be used later by the fsetpos function to reset the file-position indicator.
#include <stdioh>
int fgetpos(FILE *stream, fpos_t *pos);
stream
points to the file of which the fgetpos function ascertains the current value of the
file-position indicator.
pos
contains the current value of the file-position indicator
Return Value
is zero if the call is successful. Otherwise, a nonzero value is returned.
Usage Guidelines
•
The type fpos_t is an object type capable of recording all the information needed to
specify uniquely every position within a file.
Guardian TNS C Library Calls Reference Manual—128833
3- 43
fgets
Reference to Library Calls
fgets
The fgets function reads a string from a file opened for ANSI I/O.
#include <stdioh>
char *fgets(char *str_ptr, int str_size, FILE *stream);
str_ptr
points to the string where fgets stores the input.
str_size
specifies the size in bytes of *str_ptr. fgets reads up to str_size - 1 characters.
stream
denotes a file opened for ANSI I/O.
Return Value
is str_ptr if the operation is successful. If fgets encounters the end of the file or an
error, it returns the pointer value NULL. To distinguish between these two cases, use
the feof or ferror function.
Usage Guidelines
•
The fgets function reads from a file until it encounters a newline character or the end
of the file or until it has read str_size - 1 characters. If it encounters a newline
character, fgets copies it into *str_ptr. Following the input, fgets stores a null
character into the byte following the last character read.
Example
This example reads a string from the file $a.b.c and writes it to the array named sp:
#include <stdioh>
#define SPSIZE 200
FILE *fp;
char sp[SPSIZE];
char *cp;
fp = fopen("$a.b.c", "r");
/* ... */
cp = fgets(sp, SPSIZE, fp);
3- 44
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
fileno (supplementary)
fileno (supplementary)
The fileno function retrieves the file descriptor of a file opened for ANSI I/O.
#include <stdioh>
int fileno(FILE *stream);
stream
denotes a file opened for ANSI I/O.
Return Value
is the file descriptor if *stream refers to an open file; otherwise, fileno returns the
value -1.
Example
This example illustrates how fileno returns the file descriptor of a file opened for
ANSI I/O:
#include <stdioh>
FILE *f_ptr;
int f_desc;
f_ptr = fopen("$a.b.c", "r+");
/* ... */
f_desc = fileno(f_ptr);
Guardian TNS C Library Calls Reference Manual—128833
3- 45
floor
Reference to Library Calls
floor
The floor function computes the largest integer not greater than its argument.
#include <mathh>
double floor(double expr);
expr
is an expression of type double.
Return Value
is the largest integer not greater than expr, expressed as a double value.
Example
This example prints “The floor value of 1.090000 is 1.000000.”:
#include <mathh>
#include <stdioh>
int main(void)
{
double x, r;
x = 1.09;
r = floor(x);
printf("The floor value of %f is %f.", x, r);
}
3- 46
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
fmod
fmod
The fmod function computes the floating-point remainder of the division of its
arguments.
#include <mathh>
double fmod(double divid, double divis);
divid
is an expression of type double, specifying the dividend.
divis
is an expression of type double, specifying the divisor.
Return Value
is the floating-point remainder of the division of (divid/divis), expressed as a double
value with the same sign as divid and a magnitude less than divis. If divis is zero,
fmod returns the value of divid.
Usage Guidelines
•
The fmod function is equivalent to the following, provided that divid and divis are
expressions without side effects:
modf((divid/divis), &int_part);
return_value = divid - (int_part*divis);
Example
This example prints “The remainder is 1.000000.”:
#include <mathh>
#include <stdioh>
int main(void)
{
double r, x, y;
x = 5.0;
y = 2.0;
r = fmod(x, y);
printf ("The remainder is %f.", r);
}
Guardian TNS C Library Calls Reference Manual—128833
3- 47
fopen
Reference to Library Calls
fopen
The fopen function opens a file for ANSI I/O.
#include <stdioh>
FILE *fopen(const char *file_name, const char *access_mode);
file_name
points to a string containing a valid file name.
access_mode
points to a string that specifies how you want to access the file. The possible values
for *access_mode are described under “Usage Guidelines.”
Return Value
points to the FILE structure denoting the opened file if the operation is successful;
otherwise, fopen returns the pointer value NULL.
3- 48
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
fopen
Usage Guidelines
•
The possible values of the string *access_mode are:
"r"
Open an existing text file for read-only access.
"w"
Create a text file (or truncate an existing text file to length zero) and
open it for write-only access.
"a"
Create a text file (or open an existing text file) and open it for append
(write at the end of the file) access.
"r+"
Open an existing text file for update access (reading and writing).
"w+"
Create a text file (or truncate an existing text file to length zero) and
open it for update access.
"a+"
Create a text file (or open an existing text file) and open it for update
access with writing at the end of the file.
"rb"
Open an existing binary file for read-only access.
"wb"
Create a binary file (or truncate an existing binary file to length zero) and
open it for write-only access.
"ab"
Create a binary file (or open an existing binary file) and open it for
append (write at the end of the file) access.
"rb+"
Open an existing binary file for update access (reading and writing).
"wb+"
Create a binary file (or truncate an existing binary file to length zero) and
open it for update access.
"ab+"
Create a binary file (or open an existing binary file) and open it for
update access with writing at the end of the file.
If you attempt to open a file in read mode and the file does not exist or cannot be
read, fopen fails, returning the pointer value NULL.
When you open a file in append mode, the file-position indicator is set to the end of
the file before each write operation, regardless of previous positioning.
•
When you include a system name in the file name, you must precede the system
name with two backslashes instead of one because backslash is an escape character
in C. For example, to open the file \sys.$vol.svol.file, you would use the C string:
"\\sys.$vol.svol.file"
•
•
•
•
Unless you include b in the access string, the file is opened as a text file.
If the file does not already exist, fopen creates a C binary file if you include b in the
access string; otherwise, it creates an Edit file.
The default number of secondary extents for files created by fopen is 16.
The default number of maxextents for files created by fopen is 500.
Guardian TNS C Library Calls Reference Manual—128833
3- 49
fopen_std_file (supplementary)
Reference to Library Calls
Example
This example opens a file named $a.b.c for update (reading and writing):
#include <stdioh>
FILE *fp;
fp = fopen("$a.b.c", "r+");
fopen_std_file (supplementary)
The fopen_std_file function opens a standard file stdin, stdout, or stderr if the file was
not opened automatically because the NOSTDFILES pragma was specified or because
the main function was not written in the C language.
#include <stdioh>
short fopen_std_file(short file, short die_on_error);
file
is an integer that specifies which standard file should be opened: 0 indicates stdin, 1
indicates stdout, and 2 indicates stderr.
die_on_error
is a boolean flag that when nonzero indicates that if there is an error in attempting to
open the file the normal shutdown sequence should be executed, which includes
writing a standard message, and then calling the system procedure
PROCESS_STOP_
Return Value
indicates the status of the operation. The function returns 0 if the open is successful,
1 if the file is already open, -1 if there is a problem with a parameter, and -2 if the
open failed. The -2 is not returned if nonzero was passed for the die_on_error
parameter.
3- 50
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
fprintf
fprintf
The fprintf function writes formatted data to a file opened for ANSI I/O.
#include <stdioh>
int fprintf(FILE *stream, const char *format, [expr...]);
stream
denotes a file opened for ANSI I/O.
format
points to a string that specifies how to format the data given by expr.... This format
string is described under “Usage Guidelines.”
expr...
is a list of expressions whose values fprintf formats using *format and then prints to
*stream.
Return Value
is the number of characters output if the operation is successful; otherwise, fprintf
returns a negative value.
Usage Guidelines
•
The Format String
The fprintf function interprets the format string, *format, as a series of literal
characters and conversion specifiers. fprintf outputs the literal characters as they
appear in the format string, and uses the conversion specifiers to format the values of
the expressions in expr.... The format of a conversion specifier is:
% [flags] [width] [.precision] [modifier] conv_code
The percent sign indicates the start of a conversion specifier. Here are the
components that follow it:
•
•
flags is a list of zero or more flags that alter or modify the formatting of a
converted value.
width is an optional decimal number that specifies the minimum width (in
characters) of the field containing the value. If the converted value is shorter
than the given field width, fprintf pads the value on the left (unless you use the
left-justify flag described later) to fill the field. fprintf pads with blanks unless
width begins with a zero, in which case fprintf pads with zeros.
Guardian TNS C Library Calls Reference Manual—128833
3- 51
fprintf
Reference to Library Calls
•
precision is an optional decimal number that specifies the precision used when
formatting the converted value. How fprintf uses this number depends upon the
conversion code that follows it:
•
•
•
•
For codes d, i, o, u, x, and X, precision is the minimum number of digits to
print.
For codes e, E, and f, precision is the number of digits to print following the
decimal point.
For codes g and G, precision is the maximum number of significant digits.
For code s, precision is the maximum number of characters to print from the
string.
Note that a period precedes the number. If you omit the number (but include the
period), fprintf uses zero as the precision. Also note that the precision value
overrides the field width if the field width cannot accommodate the specified
precision.
•
•
•
modifier is an optional modifier that affects how fprintf interprets the value
being formatted.
conv_code is a conversion code that specifies the interpretation and default
formatting of the value being formatted.
Conversion Flags
Here are the possible values of flags in a conversion specifier:
-
Is the left-justify flag; it causes fprintf to pad a converted value on the
right so that it is left justified within its field.
+
Is the sign flag; it causes fprintf to print a plus sign (+) preceding a
positive value in a signed conversion.
blank (a blank character, “ ”) Is the blank flag; it causes fprintf to print a blank
preceding a positive value in a signed conversion. If you use both the sign
flag and the blank flag, fprintf ignores the blank flag.
#
Is the alternate-form flag; it causes fprintf to format the converted value
specially, based upon the conversion code:
•
•
•
3- 52
For code o, this flag causes fprintf to increase the precision so that the
first digit of the converted value is zero.
For codes x and X, this flag causes fprintf to prefix a nonzero
converted value with 0x or 0X, respectively.
For codes e, E, f, g, and G, this flag causes fprintf to include a decimal
point in the converted value, even if there are no fractional digits;
trailing zeros are not removed if the code is g or G.
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
•
fprintf
Conversion Modifiers
Here are the possible values of modifier in a conversion specifier:
•
h
For conversion codes d, i, o, u, x, and X, the h modifier indicates that the value
is a short int, not an int. For conversion code n, the h modifier indicates that
the value is a pointer to short int, not a pointer to int.
l
For conversion codes d, i, o, u, x, and X, the l modifier indicates that the value
is a long int, not an int. For conversion code n, the l modifier indicates that the
value is a pointer to long int, not a pointer to int.
L
For conversion codes e, E, f, g, and G, the L modifier indicates that the value
is a long double, not a double. For conversion codes d, i, o, x, and X, the L
modifier indicates that the value is a long long, not an int.
Conversion Codes
As mentioned earlier, conv_code determines both how fprintf interprets the
argument value and how it formats the value. This list shows the conversion codes
and describes the argument type and formatting specified by each code.
c
formats an int argument as a single character, first converting the argument to
type unsigned int.
d
formats an int argument as a signed decimal integer
e
formats a double argument as a exponential number of the form [-]d.ddde±dd,
with one digit preceding the decimal point and precision digits following it. If
precision is zero, no decimal point is printed. If the conversion specifier
doesn’t include precision, six digits follow the decimal point. The value is
rounded to the specified number of decimal digits, and the exponent always
has at least two digits.
E
is equivalent to the e code, except that it prefixes the exponent with an
uppercase E rather than a lowercase one.
f
formats a double argument as a fixed-decimal number of the form [-]ddd.ddd,
with at least one digit preceding the decimal point and precision digits
following it. If precision is zero, no decimal point is printed. If the conversion
specifier doesn’t include precision, six digits follow the decimal point. The
value is rounded to the specified number of decimal digits.
g
formats a double argument using either the e code or the f code, depending
upon the value of the argument. The e code is used only if the exponent of the
converted value is less than or equal to -4, or if it is greater than or equal to the
precision. Trailing zeros are removed from the result, and a decimal point
appears only if it is followed by a digit.
G
is equivalent to the g code, except that it selects between the E code (not the e
code) and the f code.
i
is equivalent to d.
Guardian TNS C Library Calls Reference Manual—128833
3- 53
fprintf
Reference to Library Calls
n
stores the number of characters printed thus far in the variable of type int that
is referenced by the argument. The argument must have type pointer to int.
o
formats an int argument as an unsigned octal integer.
p
formats the value of a pointer to void argument using the format specified by
the x conversion code.
s
formats the data referenced by a pointer to char argument as a string of
characters. fprintf prints characters from the data until it encounters a null
character or until it has printed precision characters.
u
formats an int argument as an unsigned decimal integer.
x
formats an int argument as an unsigned hexadecimal integer, using the
lowercase letters a through f to represent the digits 10 through 15.
X
formats an int argument as an unsigned hexadecimal integer, using the
uppercase letters A through F to represent the digits 10 through 15.
%
prints a percent sign; for example:
prints, “Stock went up %d%%\n”, increase);
Example
In this example, the fprintf function fetches an argument, converts it to a character
string, and then prints it to the file $a.b.c:
#include <stdioh>
FILE *fp;
char *x;
fp = fopen("$a.b.c", "w");
/* ... */
x = "Carolyn";
fprintf(fp, "Hello, %s", x);
3- 54
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
fputc
fputc
The fputc function writes a character to a file opened for ANSI I/O.
#include <stdioh>
int fputc(int character, FILE *stream);
character
is the character that is sent to the file.
stream
denotes a file opened for ANSI I/O.
Return Value
is the character written if the operation is successful; otherwise, fputc returns the
value EOF.
Example
In this example, the fputc function writes a character to the file $a.b.c:
#include <stdioh>
FILE *fp;
int c;
int status;
fp = fopen("$a.b.c", "w");
c = 'a';
status = fputc(c,fp);
Guardian TNS C Library Calls Reference Manual—128833
3- 55
fputs
Reference to Library Calls
fputs
The fputs function writes a string to a file opened for ANSI I/O.
#include <stdioh>
int fputs(const char *str_ptr, FILE *stream);
str_ptr
points to an array of characters.
stream
denotes a file opened for ANSI I/O.
Return Value
is the value EOF if an error occurs.
Usage Guidelines
•
The fputs function writes characters from a string to a file until it encounters a null
character. It does not write a newline character following the string.
Example
In this example, the fputs function writes “Hello” to $a.b.c:
#include <stdioh>
FILE *fp;
char *sp;
int status;
fp = fopen("$a.b.c", "w");
sp = "Hello";
status = fputs(sp, fp);
3- 56
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
fread
fread
The fread function reads data blocks from a file opened for ANSI I/O and then stores the
data blocks in an array.
#include <stdioh>
size_t fread(void *dest_ptr, size_t block_size,
size_t block_count, FILE *stream);
dest_ptr
points to the array where fread stores the input blocks.
block_size
specifies the size in bytes of the blocks.
block_count
specifies the number of blocks to read.
stream
denotes a file opened for ANSI I/O.
Return Value
is the number of blocks read if the operation is successful; otherwise, fread returns
the value zero. If the value returned is less than you expected, use the ferror and feof
functions to determine the cause.
Example
This example reads 100 blocks of data from the file $a.b.c and writes them to the array
of structures named customer:
#include <stdioh>
FILE *fp;
struct snam_tag
{
char last[20];
char first[10];
char middle;
};
struct snam_tag customer[100];
fp = fopen("$a.b.c", "r");
/* ... */
fread((void *) customer, sizeof(struct snam_tag), 100, fp);
Note that the sizeof operator in the call to fread determines the size of the blocks.
Guardian TNS C Library Calls Reference Manual—128833
3- 57
free
Reference to Library Calls
free
The free function releases a block of memory that you have allocated using calloc,
malloc, or realloc.
#include <stdlibh>
void free(void *blk_ptr);
blk_ptr
points to the block of memory to release. It must point to the first byte of the block
returned by calloc, malloc, or realloc.
Return Value
none.
Usage Guidelines
•
Attempts to free a block not allocated by calloc, malloc, or realloc cause an error
when detected.
Examples
1. This example frees the block of memory pointed to by blk:
#include <stdlibh>
char *blk;
blk = malloc(100);
free(blk);
2. This example frees the block of memory pointed to by ptr:
#include <stdlibh>
int *ptr;
/* ... */
ptr = (int *)malloc(100);
/* ... */
free(ptr);
/* ... */
3- 58
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
freopen
freopen
The freopen function opens a file for ANSI I/O by reusing an existing file pointer. It first
attempts to close the file (if any) that is already associated with the existing file pointer.
#include <stdioh>
FILE *freopen(const char *file_name, const char *access,
FILE *stream);
file_name
points to a string that contains a valid file name, specifying the file that freopen is to
open.
access
points to a string that specifies how you want to access the new file. Refer to
“fopen” on page 3-48 for the possible values of *access.
stream
denotes a file opened for ANSI I/O. stream specifies the file that freopen attempts to
close.
Return Value
is stream if the operation is successful; otherwise, freopen returns the pointer value
NULL.
Usage Guidelines
•
When you include a system name in the file name, you must precede the system
name with two backslashes instead of one because backslash is an escape character
in C. For example, to open the file \sys.$vol.svol.file, you would use the C string:
"\\sys.$vol.svol.file"
•
•
•
•
If the file does not already exist, freopen creates a C binary file if you include b in
the access string; otherwise, it creates an Edit file.
The freopen function is typically used to attach the constant names stdin, stdout, and
stderr to specified files.
The freopen function attaches a new file to a previously used file pointer, thus
permitting you to access several files consecutively without declaring a separate
FILE structure for each one.
The freopen function closes the previous file before it reuses the file pointer.
Guardian TNS C Library Calls Reference Manual—128833
3- 59
freopen
Reference to Library Calls
Example
In this example, the freopen function automatically closes $a.b.c and attaches a new file
named, $a.b.c to the same file pointer:
#include <stdioh>
FILE *fp;
FILE *fpr;
fp = fopen("$a.b.c", "r");
/* ... */
fpr = freopen("$a.b.c", "r", fp);
3- 60
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
fscanf
frexp
The frexp function splits a floating-point number into a normalized fraction and an
integral power of 2.
#include <mathh>
double frexp(double expr, int *binary_power);
expr
is an expression of type double.
binary_power
points to the variable of type int where frexp stores the integral power of 2. If expr is
zero, the power of 2 is also zero.
Return Value
is the normalized fraction, expressed as a double value. If expr is zero, frexp returns
the value zero.
Example
This example prints “The mantissa is 0.615000. The exponent is 1.”:
#include <stdioh>
#include <mathh>
int main(void)
{
double r, x;
int i;
x = 1.23;
r = frexp(x, &i);
printf("The mantissa is %f. ", r);
printf("The exponent is %d.\n", i);
}
fscanf
The fscanf function reads and scans input from a file opened for ANSI I/O, comparing it
to an expected format specified by a format string. If the input conforms to the given
expectations, fscanf converts the input data to specified types of values and stores these
values in variables that you supply.
#include <stdioh>
int fscanf(FILE *stream, const char *format, [*obj_ptr...]);
Guardian TNS C Library Calls Reference Manual—128833
3- 61
fscanf
Reference to Library Calls
stream
denotes a file opened for ANSI I/O.
format
points to a string that specifies how to convert the input text for assignment, using
subsequent arguments as pointers to the variables to receive the converted input.
This format string is described in the next subsection, “Usage Guidelines.”
obj_ptr...
is a list of pointers to variables, specifying where the results of the conversions
defined in *format are to be stored.
Return Value
is the number of items for which fscanf found valid data, including all singlecharacter items in *format that were matched. If an error occurs, fscanf returns the
value EOF.
Usage Guidelines
•
The Format String
The fscanf function interprets the format string, *format, as a series of directives that
describe how to scan, convert, and store the input read from *stream. There are three
kinds of directives:
•
•
•
Conversion specifiers
Space characters (blanks, tabs, newlines, and so on)
Plain characters (nonspace characters that are not part of a conversion specifier)
Each conversion specifier requires input from the file, which is then converted and
stored in a specified variable.
One or more space characters in *format (blanks, horizontal tabs, newline, vertical
tabs, form feeds, and comments) causes one or more consecutive space characters in
the input to be skipped over. That is, the number of consecutive space characters in
*format does not have to match the number in the input at that point.
Other characters in *format–characters that are neither characters in conversion
specifiers nor space characters–must match current input, character by character, in
order for the input process to continue.
3- 62
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
•
fscanf
Conversion Specifiers
The format of a conversion specifier is:
% [*] [width] [modifier] conv_code
The percent sign indicates the start of a conversion specifier. Here are the
components that follow it:
•
*
Is the suppression flag; it specifies that the converted value should
be discarded and not stored in the next variable referenced by
*obj_ptr....
width
Is an optional decimal number that specifies the maximum field
width.
modifier
Is an optional modifier that indicates the size of the next variable in
*obj_ptr....
conv_code
Is a conversion code that determines how fscanf scans the input
data and what type of value it converts that data to.
Conversion Modifiers
Here are the possible values of modifier in a conversion specifier:
h
indicates that the next pointer in obj_ptr... points to a short variable. For
conversion codes d, i, n, o, and x, the pointer is a pointer to short int. For
conversion code u, the pointer is a pointer to unsigned short int.
l
indicates that the next pointer in obj_ptr... points to a variable of type long.
For conversion codes d, i, n, o, and x, the pointer is a pointer to long int. For
conversion code u, the pointer is a pointer to unsigned long int. For conversion
codes e, f, and g, the pointer is a pointer to double (instead of float).
L
indicates that the next pointer in obj_ptr... points to a variable of type long
double or long long. For conversion codes e, f, and g, the pointer is a pointer
to long double. For conversion codes d, i, n, o, and x, the pointer is a pointer
to long long.
Guardian TNS C Library Calls Reference Manual—128833
3- 63
fscanf
Reference to Library Calls
•
Conversion Codes
As mentioned earlier, conv_code determines both how fscanf scans the input data
and what type of value it converts that data to. This list shows the conversion codes
and describes the scanning technique and data conversion specified by each code.
3- 64
c
matches a sequence of width characters (1 if width is omitted). The
corresponding obj_ptr must be a pointer to char that points to the first
character of an array large enough to accommodate width elements. fscanf
does not append a null character to the input data.
d
matches an optionally signed decimal integer. The corresponding obj_ptr must
be a pointer to int.
e
matches an optionally signed floating-point number that is a valid floatingpoint constant without a suffix. The corresponding obj_ptr must be a pointer
to float.
f
is equivalent to e.
g
is equivalent to e.
i
matches an optionally signed integer number that is a valid integer constant (in
octal, decimal, or hexadecimal notation). The corresponding obj_ptr must be a
pointer to int.
n
does not match any input or cause any input to be scanned. The corresponding
obj_ptr must be a pointer to int. fscanf stores the number of characters read
from the input thus far into the variable of type int specified by this pointer.
The %n conversion specifier does not increment the count of matches returned
by fscanf.
o
matches an optionally signed octal integer. The corresponding obj_ptr must be
a pointer to int.
p
matches an unsigned hexadecimal integer that uses the lowercase letters a
through f to represent the digits 10 through 15. The corresponding obj_ptr
must be a pointer to pointer to void. Consequently, the integer is interpreted as
a pointer to void.
s
matches a sequence of width characters (1 if width is omitted). The
corresponding obj_ptr must be a pointer to char that points to the first
character of an array large enough to accommodate width + 1 elements. fscanf
appends a null character to the input data.
u
matches an unsigned decimal integer. The corresponding obj_ptr must be a
pointer to int.
x
matches an optionally signed hexadecimal integer that uses the letters A
through F (in uppercase or lowercase) to represent the digits 10 through 15.
The integer may be preceded by 0x or 0X. The corresponding obj_ptr must be
a pointer to int.
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
%
fscanf
matches a literal percent sign in the input; for example:
count=fscanf(fp, “Stock went up %d%% ”, &increase);
[
•
introduces a scan set, which is a list of expected characters. The scan set
consists of all characters between the left bracket [ and its matching right
bracket ], which is the end of the conversion code. If the character following
the left bracket is a circumflex (^), fscanf reads input until it encounters one of
the characters in the scan set. If the character following the left bracket is not a
circumflex, fscanf reads input until it encounters a character not in the scan
set. In either case, fscanf reads at most width characters. The corresponding
obj_ptr must be a pointer to char that points to the first character of an array
large enough to accommodate width+1 elements. fscanf stores the matching
input data, followed by a null character, in this array. To include a right
bracket in the scan set, make it the first character of the set, as in [ ]abc] or
[^]abc].
The conversion codes must agree in number and type with the pointers in obj_ptr....
Example
In this example, fscanf reads data from $a.b.c, converts it to a double value, and places it
in the variable x:
#include <stdioh>
FILE *fp;
int status;
double r;
double x;
fp = fopen("$a.b.c", "r");
/* ... */
status = fscanf(fp, "%f", &x);
r = sqrt(x);
printf("The square root of %f is %f", x, r);
Guardian TNS C Library Calls Reference Manual—128833
3- 65
fseek
Reference to Library Calls
fseek
The fseek function sets the file-position indicator of a byte-addressable file opened for
ANSI I/O.
#include <stdioh>
int fseek(FILE *stream, long pos, int pos_base);
stream
denotes a file opened for ANSI I/O.
pos
specifies the desired file position.
pos_base
is one of the following alternatives:
•
•
•
SEEK_SET indicates that pos is the number of characters from the beginning of
the file.
SEEK_CUR indicates that pos is the number of characters from the current file
position.
SEEK_END indicates that pos is the number of characters from the end of the
file.
Return Value
is zero if the operation is successful or a nonzero value if an error occurs.
Usage Guidelines
•
•
•
•
3- 66
The fseek function sets the file-position indicator to the signed offset distance from
the beginning, current position, or end of file, according to the pos_base you specify.
The fseek function has no effect if the file does not support positioning requests (a
terminal, for example). Such an unsupported request is not an error, so fseek still
returns zero.
The fseek function undoes any effects of ungetc.
The fseek function resets the end-of-file and error indicators.
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
fsetpos
Example
In this example, the fseek function sets the file-position indicator to the beginning of the
file:
#include <stdioh>
FILE *fp;
int status;
long pos;
fp = fopen("$a.b.c", "r+");
/* ... */
pos = 0;
status = fseek(fp, pos, SEEK_SET);
fsetpos
The fsetpos function sets the file-position indicator for the file pointed to by stream to
the value pointed to by pos. This value was obtained from an earlier call to the fgetpos
function on the same file.
#include <stdioh>
int fsetpos(FILE *stream, const fpos_t *pos);
stream
points to the file whose file indicator is to be reset.
pos
points to the variable that holds the stored value of the file indicator.
Return Value
is zero if successful and clears the end-of-file indicator. Otherwise, a nonzero value
is returned and errno is set to a positive value.
Guardian TNS C Library Calls Reference Manual—128833
3- 67
ftell
Reference to Library Calls
ftell
The ftell function retrieves the file-position indicator of a byte-addressable file opened
for ANSI I/O. This file-position indicator corresponds to the current byte offset from the
beginning of the file.
#include <stdioh>
long ftell(FILE *stream);
stream
denotes a file opened for ANSI I/O.
Return Value
is the file-position indicator, expressed as a long value.
Example
In this example, the ftell function returns the file-position indicator of $a.b.c:
#include <stdioh>
FILE *fp;
long pos;
fp = fopen("$a.b.c", "r");
/* ... */
pos = ftell(fp);
3- 68
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
fwrite
fwrite
The fwrite function writes contiguous blocks of data to a file opened for ANSI I/O.
#include <stdioh>
size_t fwrite(const void *first_block, size_t block_size,
size_t block_count, FILE *stream);
first_block
points to the first block of data to be written.
block_size
specifies the size (in bytes) of each block to be written.
block_count
specifies the number of blocks to be written.
stream
denotes a file opened for ANSI I/O.
Return Value
is the number of blocks written if the operation is successful; otherwise, fwrite
returns the value zero. If the value returned is less than you expected, use the ferror
and feof functions to determine the cause.
Example
In this example, the fwrite function writes one block of data from the array named block
to $a.b.c:
#include <stdioh>
FILE *fp;
int block[100];
int status;
fp = fopen("$a.b.c", "w");
/* ... */
status = fwrite((void *)block, sizeof block, 1, fp);
Guardian TNS C Library Calls Reference Manual—128833
3- 69
get_assign_msg (supplementary)
Reference to Library Calls
get_assign_msg (supplementary)
The get_assign_msg function retrieves a specified assign message. You define which
assign message is retrieved by specifying the ordinal number that corresponds to the
desired message’s position in the series of assign messages for a particular process.
#include <stdlibh>
short get_assign_msg(short assign_num,
assign_msg_type *assign_msg);
assign_num
the number that specifies the assign message’s position in the series of assign
messages defined for a particular process.
assign_msg
points to a structure of type assign_msg_type that is declared in the header stdlibh.
See “Usage Guidelines” on page 3-71 for more details regarding this type. The
get_assign_msg function copies the assign message into the structure pointed to by
this assign_msg parameter.
Return Value
is 0 if the assign message is found, and -1 if the assign message is not found.
3- 70
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
get_assign_msg (supplementary)
Usage Guidelines
•
The type assign_msg_type is declared in the header stdlibh as:
typedef struct
{
short msg_code;
struct
{
char prognamelen;
char progname[31];
char filenamelen;
char filename [31];
} logical_unit_name;
unsigned long field_mask;
union
{
char whole[24];
struct
{
char volume[8];
char subvolume[8];
char file [8];
} parts;
} filename;
short primary_extent;
short secondary_extent;
short file_code;
short exclusion_spec;
short access_spec;
short record_size;
short block_size;
} assign_msg_type;
Guardian TNS C Library Calls Reference Manual—128833
3- 71
get_assign_msg (supplementary)
•
Reference to Library Calls
For portability, programs can specify logical units, such as TAPEFILE or PRINTER,
instead of the names of actual files or devices. The TACL ASSIGN command, or the
#ASSIGN built-in variable, associates a specific file or device with a given logical
unit to represent that actual entity when you run the program.
In the type assign_msg_type, the structure members provide the following
information:
msg_code
value of -2 for an ASSIGN message
logical_unit_name
name of logical unit used in program and consists of
program unit and file name
field_mask
bit mask that indicates which of the following fields
were supplied (1 = supplied):
.<0> = physical file name
.<1> = primary extent size
.<2> = secondary extent size
.<3> = file code
.<4> = exclusion size
.<5> = access specifier
.<6> = record size
.<7> = block size
filename
physical file name to be associated with logical unit
primary_extent
primary extent size
secondary_extent
secondary extent size
file_code
file-code
exclusion_spec
exclusion mode:
%00 if SHARED
%20 if EXCLUSIVE
%60 if PROTECTED
access_spec
access mode:
%0000 if read/write
%2000 if read only
%4000 if write only
3- 72
record_size
record size
block_size
block size
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
get_assign_msg_by_ name (supplementary)
get_assign_msg_by_ name (supplementary)
The get_assign_msg_by_name function retrieves the assign message that corresponds to
the logical-unit name requested.
#include <stdlibh>
short get_assign_msg_by_name(char *assign_name,
assign_msg_type *assign_msg);
assign_name
points to the NULL terminated logical-unit name.
assign_msg
points to a structure of type assign_msg_type that is declared in the header stdlibh.
See “Usage Guidelines” on page 3-74 for more details regarding this type. The
get_assign_msg_by_name function copies the assign message into the structure
pointed to by this assign_msg parameter.
Return Value
is 0 if the assign message is found, and -1 if the assign message is not found.
Guardian TNS C Library Calls Reference Manual—128833
3- 73
get_assign_msg_by_ name (supplementary)
Reference to Library Calls
Usage Guidelines
•
The type assign_msg_type is declared in the header stdlibh as:
typedef struct
{
short msg_code;
struct
{
char prognamelen;
char progname[31];
char filenamelen;
char filename [31];
} logical_unit_name;
unsigned long field_mask;
union
{
char whole[24];
struct
{
char volume[8];
char subvolume[8];
char file [8];
} parts;
} filename;
short primary_extent;
short secondary_extent;
short file_code;
short exclusion_spec;
short access_spec;
short record_size;
short block_size;
} assign_msg_type;
3- 74
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
•
get_assign_msg_by_ name (supplementary)
For portability, programs can specify logical units, such as TAPEFILE or PRINTER,
instead of the names of actual files or devices. The TACL ASSIGN command, or the
#ASSIGN built-in variable, associates a specific file or device with a given logical
unit to represent that actual entity when you run the program
In the type assign_msg_type, the structure members provide the following
information:
msg_code
value of -2 for an ASSIGN message
logical_unit_name
name of logical unit used in program and consists of
program unit and file name
field_mask
bit mask that indicates which of the following fields
were supplied (1 = supplied):
.<0> = physical file name
.<1> = primary extent size
.<2> = secondary extent size
.<3> = file code
.<4> = exclusion size
.<5> = access specifier
.<6> = record size
.<7> = block size
filename
physical file name to be associated with logical unit
primary_extent
primary extent size
secondary_extent
secondary extent size
file_code
file-code
exclusion_spec
exclusion mode:
%00 if SHARED
%20 if EXCLUSIVE
%60 if PROTECTED
access_spec
access mode:
%0000 if read/write
%2000 if read only
%4000 if write only
record_size
record size
block_size
block size
Guardian TNS C Library Calls Reference Manual—128833
3- 75
get_max_assign_msg_ordinal (supplementary)
Reference to Library Calls
get_max_assign_msg_ordinal (supplementary)
The get_max_assign_msg_ordinal function determines how many assign messages are
assigned to a particular process.
#include <stdlibh>
short get_max_assign_msg_ordinal(void);
Return Value
is the number of assign messages that exist for a particular process.
Usage Guidelines
•
To determine the number of assign messages, the get_max_assign_msg_ordinal
function begins counting at 1.
Example
This example uses the get_max_assign_msg_ordinal function to determine the total
number of assign messages that exist for a particular process, and then retrieves the
assign messages.
#include <stdlibh>
short i;
short j;
assign_msg_type assign_msg_array[10];
/* ... */
j = get_max_assign_message_ordinal;
for (i = 0; i <= j; i++)
{
status = get_assign_msg (i, &assign_msg_array[i]);
status != 0)
printf("Assign message %d not found.\n", i);
}
get_param_by_name (supplementary)
The get_param_by_name function retrieves the value of the parameter that corresponds
to the parameter name requested.
#include <stdlibh>
short get_param_by_name(char *param_name,
char *param_value,
short max_len);
3- 76
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
get_param_by_name (supplementary)
param_name
points to the NULL terminated name of the parameter.
param_value
points to the NULL terminated value assigned to the parameter name.
max_len
is the maximum length of the NULL terminated string that can be copied to
param_value. This string is the parameter value.
Return Value
is 0 if the parameter name is found, -1 if the parameter name is not found, and -2 if
the parameter name is found but the buffer provided to contain the value is too
small.
Usage Guidelines
•
In order to use the get_param_by_name function in your C program, you must
create one or more parameters before running your program. Use the TACL PARAM
command at the TACL prompt to create the parameters. This example creates two
parameters, parameter a has the value abc and parameter CLIB has the value
$lang4.T9255d.
30> PARAM
31> PARAM
•
a
CLIB
abc
$lang4.T9255d
If you want to display the parameters you entered, enter the PARAM command
without a parameter name or parameter value. For example:
32> PARAM
could provide you with the following list:
a
CLIB
•
abc
$lang4.T9255d
After you create the desired parameters, you can run your C program. In your
C program there are one or more get_param_by_name functions. Each function
retrieves the value of the parameter that corresponds to the parameter name
requested. For example, these functions might be in your C program:
get_param_by_name("a");
get_param_by_name("CLIB");
Guardian TNS C Library Calls Reference Manual—128833
3- 77
get_param_msg (supplementary)
Reference to Library Calls
get_param_msg (supplementary)
The get_param_msg function retrieves the param message.
#include <stdlibh>
short get_param_msg(param_msg_type *param_msg,
short *actual_len);
param_msg
points to a structure of type param_msg_type that is declared in the header stdlibh.
See “Usage Guidelines” for more details regarding this type. The get_param_msg
function copies the param message into the structure pointed to by this param_msg
parameter.
actual_len
points to the short integer where get_param_msg copies the actual length of the
param message.
Return Value
is 0 if the param message is found, and -1 if the param message is not found.
Usage Guidelines
•
The type param_msg_type is declared in the header stdlibh as:
typedef struct
{
short msg_code;
short num_params;
char parameters[1024];
} param_msg_type;
•
In the type param_msg_type, the structure members provide the following
information:
msg_code
value of -3 for a param message
num_params
number of parameters in the message
parameters[1024]
the parameters with each parameter having this structure:
= “n”, length in bytes of
parameter name
param[0]
param[1]
FOR n
= “v”, length in bytes of
parameter value
param[n+1]
param[n+2]
3- 78
= parameter name
FOR v
= parameter value
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
get_startup_msg (supplementary)
get_startup_msg (supplementary)
The get_startup_msg function retrieves the process startup message.
#include <stdlibh>
short get_startup_msg(startup_msg_type *startup_msg,
short *actual_len);
startup-msg
points to a structure of type startup_msg_type that is declared in the header
<stdlibh>. See “Usage Guidelines” on page 3-80 for more details regarding this
type. The get_startup_msg function copies the startup message into the structure
pointed to by this startup_msg parameter.
actual_len
points to the short integer where get_startup_msg copies the actual length of the
startup message.
Return Value
is 0 if the startup message is found, and -1 if the startup message is not found.
Guardian TNS C Library Calls Reference Manual—128833
3- 79
get_startup_msg (supplementary)
Reference to Library Calls
Usage Guidelines
•
The type startup_msg_type is declared in the header stdlibh as:
typedef struct
{
short msg_code;
union
{
char whole[16];
struct
{
char volume[8];
char subvolume[8];
} parts;
} defaults;
union
{
char whole[24];
struct
{
char volume[8];
char subvolume[8];
char file[8];
} parts;
} infile;
union
{
char whole[24];
struct
{
char volume[8];
char subvolume[8];
char file[8];
} parts;
} outfile;
char param[530];
} startup_msg_type;
•
In the type startup_msg_type, the structure members provide the following
information:
msg_code
message type; -1 means a startup message
defaults
default volume and subvolume names
infile
volume, subvolume, and file name of input file
outfile
volume, subvolume, and file name of output file
param[530] text of message
3- 80
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
get_startup_msg (supplementary)
Examples
1. The C RUN command can have the form
C/ IN in_file_name, OUT out_file_name/ c_object_file; pragma,
pragma
The startup message reflecting this command has the following components:
msg_code
-1
defaults
user’s default volume and subvolume
infile
in_file_name
outfile
out_file_name
char param[]
c_object_file, pragma, pragma
2. In this example, the get_startup_msg function retrieves the startup message and puts
it in the structure my_startup_message.
#include <stdlibh>
short msg_length;
short status;
startup_msg_type my_startup_msg;
/* ... */
status = get_startup_msg(&my_startup_msg, &msg_length);
if(status != 0) printf("Startup message not found.");
Guardian TNS C Library Calls Reference Manual—128833
3- 81
getc
Reference to Library Calls
getc
The getc function reads a character from a file opened for ANSI I/O.
#include <stdioh>
int getc(FILE *stream);
stream
denotes a file opened for ANSI I/O.
Return Value
is the character retrieved from the file. If getc encounters the end of the file or an
error, it returns the value EOF. To distinguish between these two cases, use the feof
or ferror function.
Usage Guidelines
•
The getc function might be implemented as a macro in a future release.
Consequently, you should use the fgetc function (rather than getc) if you are
concerned about the amount of memory in a macro expansion or about side effects.
getchar
The getchar function reads a character from the standard input file, stdin.
#include <stdioh>
int getchar(void);
Return Value
is the character retrieved from the standard input file. If getchar encounters the end
of the file or an error, it returns the value EOF. To distinguish between these two
cases, use the feof or ferror function.
Usage Guidelines
•
The getchar function might be implemented as a macro in a future release.
Example
This example gets a character from the standard input file:
#include <stdioh>
int c;
c = getchar();
3- 82
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
getenv
getenv
The getenv function retrieves the value of a run-time parameter from the environment
array.
#include <stdlibh>
char *getenv(const char *env_parm);
env_parm
points to a string containing the name of the run-time parameter whose value you
want to retrieve. This string must be in uppercase. Possible values for *env_parm are
described under “Usage Guidelines.”
Return Value
is the value of the run-time parameter you specified in *env_parm. The value is
NULL if an error occurs.
Usage Guidelines
•
The environment array always contains the following four run-time parameters, as
you would specify them in *env_parm:
"STDIN"
Gives the file name of the standard input file, stdin.
"STDOUT"
Gives the file name of the standard output file, stdout.
"STDERR"
Gives the file name of the standard error file, stderr.
"DEFAULTS"
Gives the default volume and subvolume names used to qualify
partial file names.
In addition to these four parameters, the environment array contains values for all
user-defined parameters (PARAMs) active when your C program starts.
•
If the main routine of a mixed-language program is not written in C, the value of the
SAVE-ENVIRONMENT PARAM must be set to ON to use the getenv function.
Refer to the Common Run-Time Environment (CRE) Programmer’s Guide for more
information.
Guardian TNS C Library Calls Reference Manual—128833
3- 83
gets
Reference to Library Calls
gets
The gets function reads a string from the standard input file, stdin.
#include <stdioh>
char *gets(char *str_ptr);
str_ptr
points to the string where gets stores the input string.
Return Value
is str_ptr if the operation is successful. If gets encounters the end of the file or an
error, it returns the pointer value NULL. To distinguish between these two cases, use
the feof or ferror function.
Usage Guidelines
•
•
The gets function reads until it encounters the end of the line.
Unlike fgets, which passes the newline character with a null character appended,
gets replaces the newline with a null.
Example
This example reads a string from the standard input file and stores it in the array named
sp:
#include <stdioh>
char *p;
char sp[200];
p = gets(sp);
3- 84
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
gmtime
gmtime
The gmtime function converts the calendar time pointed to by timer to a broken-down
time, and stores the broken-down time in a structure of type struct tm that is provided for
you. The gmtime function returns the address of the structure.
#include <timeh>
struct tm *gmtime(const time_t *timer);
timer
points to the calendar time.
Return Value
points to the structure of type struct tm that contains the Coordinated Universal Time
(UTC).
Usage Guidelines
•
The structure type struct tm is defined in the header timeh and has the following
members:
struct tm{
int tm_sec;
int tm_min;
int tm_hour;
int tm_mday;
int tm_mon;
int tm_year;
int tm_wday;
int tm_yday;
int tm_isdst;
};
/*
/*
/*
/*
/*
/*
/*
/*
/*
seconds after the minute: [0, 61]*/
minutes after the hour: [0, 59] */
hours since midnight: [0, 23]
*/
day of the month: [1, 31]
*/
months since January: [0, 11]
*/
years since 1900
*/
days since Sunday; [0, 6]
*/
days since January 1: [0, 365]
*/
Daylight Savings Time flag
*/
Note that the flag tm_isdst is positive if Daylight Savings Time is in effect, zero if it
is not, and negative if the information is not available.
•
Coordinated Universal Time (UTC) is a synonym for Greenwich Mean Time
(GMT).
Guardian TNS C Library Calls Reference Manual—128833
3- 85
heap_check (supplementary)
Reference to Library Calls
heap_check (supplementary)
The heap_check function checks the consistency of the run-time heap used by the
memory-management functions calloc, free, malloc, and realloc.
#include <stdlibh>
void heap_check(void);
Usage Guidelines
•
If heap_check discovers an inconsistency in the run-time heap, it prints an error
message to stderr and then calls exit with the argument EXIT_FAILURE.
heap_check_always (supplementary)
The heap_check_always function controls whether the memory-management functions
calloc, free, malloc, and realloc automatically check the consistency of the run-time
heap.
#include <stdlibh>
void heap_check_always(int switch);
switch
specifies whether to enable or disable automatic consistency checking of the
run-time heap. A nonzero value of switch enables automatic checking, and the value
zero disables automatic checking.
Usage Guidelines
•
•
3- 86
When automatic consistency checking is enabled, the memory-management
functions listed earlier perform the consistency check by calling heap_check.
Consequently, an inconsistency discovered by automatic checking has the same
impact as one discovered by calling heap_check.
Enabling automatic consistency checking degrades the performance of heap
operations significantly. Thus, you should disable automatic checking after
developing and debugging your application.
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
_is_system_trap (supplementary)
heap_min_block_size (supplementary)
The heap_min_block_size function suggests to the run-time library what the minimum
block size should be when an allocation is made from the heap.
#include <stdlibh>
void heap_min_block_size(long min_block_size);
min_block_size
specifies the number of bytes to be allocated.
Usage Guidelines
•
If a C program makes many calls to the malloc, calloc, or free functions to allocate
and deallocate small blocks of memory and these calls are interspersed with many
calls to allocate large blocks of memory, the heap can become very fragmented with
many small, almost useless free blocks. This memory configuration can have a
detrimental effect on the run-time efficiency of the routines that traverse the “freelist” searching for a block of memory of the proper size to allocate. By judiciously
choosing a value for heap_min_block_size, you can tune the performance of your
program.
_is_system_trap (supplementary)
The _is_system_trap function can be used in the handler to determine whether the
current trap happens in system code.
#include <signalh>
sig_atomic_t _is_system_trap(void)
Return Value
is zero if the current trap did not happen in system code. Otherwise, the return value
is nonzero, which indicates that the trap did occur in system code. The return value
is undefined if this function is called from a function that is not a signal handler.
Guardian TNS C Library Calls Reference Manual—128833
3- 87
isalnum
Reference to Library Calls
isalnum
The isalnum function tests whether its argument is alphanumeric.
#include <ctypeh>
int isalnum(int character);
character
specifies the character to test.
Return Value
is nonzero if character is an uppercase or lowercase character or a digit; otherwise,
isalnum returns the value zero.
Usage Guidelines
•
3- 88
The character-testing routine isalnum is implemented as a macro, but the C compiler
provides an underlying function with the same name as the macro. Although the
macro is faster than the function, it evaluates its argument more than once.
Consequently, if you need to provide an expression with side effects as the argument
to this routine, you should undefine the macro so that the C compiler uses the
function instead. For more information about undefining macros, refer to the C/C++
Programmer’s Guide.
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
isalpha
isalpha
The isalpha function tests whether its argument is alphabetic.
#include <ctypeh>
int isalpha(int character);
character
specifies the character to test.
Return Value
is nonzero if character is an uppercase or lowercase character; otherwise, isalpha
returns the value zero.
Usage Guidelines
•
The character-testing routine isalpha is implemented as a macro, but the C compiler
provides an underlying function with the same name as the macro. Although the
macro is faster than the function, it evaluates its argument more than once.
Consequently, if you need to provide an expression with side effects as the argument
to this routine, you should undefine the macro so that the C compiler uses the
function instead. For more information about undefining macros, refer to the C/C++
Programmer’s Guide.
Guardian TNS C Library Calls Reference Manual—128833
3- 89
isascii (supplementary)
Reference to Library Calls
isascii (supplementary)
The isascii function tests whether its argument is in the range 0 through 127.
#include <ctypeh>
int isascii(int character);
character
specifies the character to test.
Return Value
is nonzero if character is in the range 0 through 127; otherwise, isascii returns the
value zero.
Usage Guidelines
•
•
3- 90
The character-testing routine isascii is implemented as a macro, but the C compiler
provides an underlying function with the same name as the macro. Although the
macro is faster than the function, it evaluates its argument more than once.
Consequently, if you need to provide an expression with side effects as the argument
to this routine, you should undefine the macro so that the C compiler uses the
function instead. For more information about undefining macros, refer to the C/C++
Programmer’s Guide.
The ISO/ANSI C standard does not specify isascii. However, the POSIX.1 standard
and XPG4 specification specify isascii.
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
iscntrl
iscntrl
The iscntrl function tests whether its argument is a control character.
#include <ctypeh>
int iscntrl(int character);
character
specifies the character to test.
Return Value
is nonzero if character is a control character; otherwise, iscntrl returns the value
zero.
Usage Guidelines
•
The character-testing routine iscntrl is implemented as a macro, but the C compiler
provides an underlying function with the same name as the macro. Although the
macro is faster than the function, it evaluates its argument more than once.
Consequently, if you need to provide an expression with side effects as the argument
to this routine, you should undefine the macro so that the C compiler uses the
function instead. For more information about undefining macros, refer to the C/C++
Programmer’s Guide.
Guardian TNS C Library Calls Reference Manual—128833
3- 91
iscsym (supplementary)
Reference to Library Calls
iscsym (supplementary)
The iscsym function tests whether its argument is a valid character for a C identifier.
#include <ctypeh>
int iscsym(int character);
character
specifies the character to test.
Return Value
is nonzero if character is a character that can be used in a C identifier; otherwise,
iscsym returns the value zero.
Usage Guidelines
•
3- 92
The character-testing routine iscsym is implemented as a macro, but the C compiler
provides an underlying function with the same name as the macro. Although the
macro is faster than the function, it evaluates its argument more than once.
Consequently, if you need to provide an expression with side effects as the argument
to this routine, you should undefine the macro so that the C compiler uses the
function instead. For more information about undefining macros, refer to the C/C++
Programmer’s Guide.
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
iscsymf (supplementary)
iscsymf (supplementary)
The iscsymf function tests whether its argument is valid as the first character of a
C identifier.
#include <ctypeh>
int iscsymf(int character);
character
specifies the character to test.
Return Value
is nonzero if character is a character that can start a C identifier; otherwise, iscsymf
returns the value zero.
Usage Guidelines
•
The character-testing routine iscsymf is implemented as a macro, but the C compiler
provides an underlying function with the same name as the macro. Although the
macro is faster than the function, it evaluates its argument more than once.
Consequently, if you need to provide an expression with side effects as the argument
to this routine, you should undefine the macro so that the C compiler uses the
function instead. For more information about undefining macros, refer to the C/C++
Programmer’s Guide.
Guardian TNS C Library Calls Reference Manual—128833
3- 93
isdigit
Reference to Library Calls
isdigit
The isdigit function tests whether its argument is a decimal digit.
#include <ctypeh>
int isdigit(int character);
character
specifies the character to test.
Return Value
is nonzero if character is a decimal digit; otherwise, isdigit returns the value zero.
Usage Guidelines
•
3- 94
The character-testing routine isdigit is implemented as a macro, but the C compiler
provides an underlying function with the same name as the macro. Although the
macro is faster than the function, it evaluates its argument more than once.
Consequently, if you need to provide an expression with side effects as the argument
to this routine, you should undefine the macro so that the C compiler uses the
function instead. For more information about undefining macros, refer to the C/C++
Programmer’s Guide.
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
isgraph
isgraph
The isgraph function tests whether its argument is a printable character other than a
blank (“ ”).
#include <ctypeh>
int isgraph(int character);
character
specifies the character to test.
Return Value
is nonzero if character is a printable character other than a blank; otherwise, isgraph
returns the value zero.
Usage Guidelines
•
The character-testing routine isgraph is implemented as a macro, but the C compiler
provides an underlying function with the same name as the macro. Although the
macro is faster than the function, it evaluates its argument more than once.
Consequently, if you need to provide an expression with side effects as the argument
to this routine, you should undefine the macro so that the C compiler uses the
function instead. For more information about undefining macros, refer to the C/C++
Programmer’s Guide.
Guardian TNS C Library Calls Reference Manual—128833
3- 95
islower
Reference to Library Calls
islower
The islower function tests whether its argument is a lowercase letter.
#include <ctypeh>
int islower(int character);
character
specifies the character to test.
Return Value
is nonzero if character is a lowercase letter; otherwise, islower returns the value
zero.
Usage Guidelines
•
3- 96
The character-testing routine islower is implemented as a macro, but the C compiler
provides an underlying function with the same name as the macro. Although the
macro is faster than the function, it evaluates its argument more than once.
Consequently, if you need to provide an expression with side effects as the argument
to this routine, you should undefine the macro so that the C compiler uses the
function instead. For more information about undefining macros, refer to the C/C++
Programmer’s Guide.
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
isprint
isprint
The isprint function tests whether its argument is a printable character.
#include <ctypeh>
int isprint(int character);
character
specifies the character to test.
Return Value
is nonzero if character is a printable character; otherwise, isprint returns the value
zero.
Usage Guidelines
•
The character-testing routine isprint is implemented as a macro, but the C compiler
provides an underlying function with the same name as the macro. Although the
macro is faster than the function, it evaluates its argument more than once.
Consequently, if you need to provide an expression with side effects as the argument
to this routine, you should undefine the macro so that the C compiler uses the
function instead. For more information about undefining macros, refer to the C/C++
Programmer’s Guide.
Guardian TNS C Library Calls Reference Manual—128833
3- 97
ispunct
Reference to Library Calls
ispunct
The ispunct function tests whether its argument is a punctuation character.
#include <ctypeh>
int ispunct(int character);
character
specifies the character to test.
Return Value
is nonzero if character is a punctuation character; otherwise, ispunct returns the
value zero.
Usage Guidelines
•
3- 98
The character-testing routine ispunct is implemented as a macro, but the C compiler
provides an underlying function with the same name as the macro. Although the
macro is faster than the function, it evaluates its argument more than once.
Consequently, if you need to provide an expression with side effects as the argument
to this routine, you should undefine the macro so that the C compiler uses the
function instead. For more information about undefining macros, refer to the C/C++
Programmer’s Guide.
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
isspace
isspace
The isspace function tests whether its argument is a space character (a blank, tab, or
newline).
#include <ctypeh>
int isspace(int character);
character
specifies the character to test.
Return Value
is nonzero if character is a space character (a blank, horizontal or vertical tab, or
newline); otherwise, isspace returns the value zero.
Usage Guidelines
•
The character-testing routine isspace is implemented as a macro, but the C compiler
provides an underlying function with the same name as the macro. Although the
macro is faster than the function, it evaluates its argument more than once.
Consequently, if you need to provide an expression with side effects as the argument
to this routine, you should undefine the macro so that the C compiler uses the
function instead. For more information about undefining macros, refer to the C/C++
Programmer’s Guide.
Guardian TNS C Library Calls Reference Manual—128833
3- 99
isupper
Reference to Library Calls
isupper
The isupper function tests whether its argument is an uppercase letter.
#include <ctypeh>
int isupper(int character);
character
specifies the character to test.
Return Value
is nonzero if character is an uppercase letter; otherwise, isupper returns the value
zero.
Usage Guidelines
•
3- 100
The character-testing routine isupper is implemented as a macro, but the C compiler
provides an underlying function with the same name as the macro. Although the
macro is faster than the function, it evaluates its argument more than once.
Consequently, if you need to provide an expression with side effects as the argument
to this routine, you should undefine the macro so that the C compiler uses the
function instead. For more information about undefining macros, refer to the C/C++
Programmer’s Guide.
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
isxdigit
isxdigit
The isxdigit function tests whether its argument is a hexadecimal digit.
#include <ctypeh>
int isxdigit(int character);
character
specifies the character to test.
Return Value
is nonzero if character is a hexadecimal digit; otherwise, isxdigit returns the value
zero.
Usage Guidelines
•
The character-testing routine isxdigit is implemented as a macro, but the C compiler
provides an underlying function with the same name as the macro. Although the
macro is faster than the function, it evaluates its argument more than once.
Consequently, if you need to provide an expression with side effects as the argument
to this routine, you should undefine the macro so that the C compiler uses the
function instead. For more information about undefining macros, refer to the C/C++
Programmer’s Guide.
Guardian TNS C Library Calls Reference Manual—128833
3 -101
labs
Reference to Library Calls
labs
The labs function returns the absolute value of its argument.
#include <stdlibh>
long labs(long expr);
expr
is an expression whose value has type long.
Return Value
is the absolute value of expr.
Usage Guidelines
•
The absolute value of the most negative long integer (LONG_MIN) cannot be
represented.
Example
This example prints “The absolute value of -100000 is 100000.”
#include <stdioh>
#include <stdlibh>
int main(void)
{
long r, x;
x = -100000;
r = labs(x);
printf("The absolute value of %ld is %ld.", x, r);
}
3- 102
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
ldexp
ldexp
The ldexp function multiplies a floating-point number by an integral power of 2.
#include <mathh>
double ldexp(double expr1, int expr2);
expr1
is an expression of type double.
expr2
is an expression of type int.
Return Value
is the value expr1*2expr2. If an overflow occurs, ldexp returns the value
HUGE_VAL. If an underflow occurs, it returns the value zero. In either of these
cases, ldexp sets errno to ERANGE (a range error).
Example
This example prints “The result is 4.920000.”:
#include <mathh>
#include <stdioh>
int main(void)
{
double r, x;
int i;
x = 1.23;
i = 2;
r = ldexp(x, i);
printf("The result is %f.", r);
}
Guardian TNS C Library Calls Reference Manual—128833
3 -103
ldiv
Reference to Library Calls
ldiv
The ldiv function computes the long quotient and long remainder that result from the
integral division of its two long arguments.
#include <stdlibh>
ldiv_t ldiv(long dividend, long divisor);
dividend
specifies the dividend, or numerator, of the integral division equation.
divisor
specifies the divisor, or denominator, of the integral division equation.
Return Value
is a structure of type ldiv_t, which comprises two long members, quot and rem, that
respectively contain the quotient and remainder resulting from the integral division
of dividend by divisor.
3- 104
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
localeconv
localeconv
The localeconv function returns a pointer to a structure of type lconv that contains
information that reflects the rules of the current locale. The standard C locale is the only
locale supported in this release.
#include <localeh>
struct lconv *localeconv(void);
Usage Guidelines
•
The lconv structure is defined as follows:
struct lconv {
/* Members controlled by the LC_MONETARY category */
char *currency_symbol;
char *int_curr_symbol;
/* monetary decimal point */
/* international (ISO) currency
symbol */
char *mon_decimal_point; /* monetary decimal point */
char *mon_thousands_sep; /* separator for groups of
digits */
char *mon_grouping;
/* size of each group of mon.
digits */
char *positive_sign;
/* positive monetary value
indicator */
char *negative_sign;
/* negative monetary value
indicator */
char frac_digits;
/* number of digits after
decimal */
char p_cs_precedes;
/* currency symbol precedes
positive */
char p_sep_by_space;
/* currency symbol separated by
space */
char n_cs_precedes;
/* currency symbol precedes
negative */
char n_sep_by_space;
/* currency symbol separated by
space */
char p sign posn;
/* positive sign position */
char n_sign_posn;
/* negative sign position */
/* Members controlled by the LC_NUMERIC category */
char *decimal point;
char *grouping;
char *thousands_sep;
/* non-monetary decimal point */
/* size of groups of non-monetary
digits */
/* separator symbol for groups of
digits */
};
Guardian TNS C Library Calls Reference Manual—128833
3 -105
localtime
Reference to Library Calls
localtime
The localtime function converts the calendar time pointed to by timer into a brokendown local time, and stores this broken-down local time in a structure of type struct tm
that is provided for you. The localtime function returns the address of the structure.
Local time is the calendar time expressed for some specific time zone.
#include <timeh>
struct tm *localtime(const time_t *timer);
timer
points to the calendar time.
Return Value
points to the broken-down local time that is stored in a structure of type struct tm.
log
The log function computes the natural (base e) logarithm of its argument.
#include <mathh>
double log(double expr);
expr
is an expression of type double, with a value greater than zero.
Return Value
is the natural logarithm of expr. If expr is less than or equal to zero, log returns the
value HUGE_VAL and sets errno to EDOM (a domain error).
Example
This example prints “The log of 1.000000 is 0.000000.”:
#include <mathh>
#include <stdioh>
int main(void)
{
double r, x;
x = 1.0;
r = log(x);
printf("The log of %f is %f.", x, r);
}
3- 106
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
log10
log10
The log10 function computes the common (base 10) logarithm of its argument.
#include <mathh>
double log10(double expr);
expr
is an expression of type double with a value greater than zero.
Return Value
is the base 10 logarithm of expr. If expr is less than or equal to zero, log10 returns
the value HUGE_VAL and sets errno to EDOM (a domain error).
Example
This example prints “The base 10 log of 256.000000 is 2.408240.”:
#include <mathh>
#include <stdioh>
int main(void)
{
double r, x;
x = 256.0;
r = log10(x);
printf("The base 10 log of %f is %f.", x, r);
}
Guardian TNS C Library Calls Reference Manual—128833
3 -107
longjmp
Reference to Library Calls
longjmp
The longjmp function restores the calling environment saved by the most recent call to
setjmp.
#include <setjmph>
void longjmp(jmp_buf env, int val);
env
is a buffer of type jmp_buf used in an earlier call to setjmp.
val
specifies the value longjmp is to cause its corresponding setjmp to return. If val is
zero, the setjmp call returns the value 1, as zero is reserved by the run-time library.
Return Value
none. However, after the call to longjmp, program execution resumes as if the
corresponding setjmp call had just returned the value val.
Usage Guidelines
•
•
•
•
3- 108
To restore the calling environment (in this context) means to restore the stack to the
way it was when setjmp was called. If a function f calls setjmp and then calls
function g1 which calls g2 which calls g3, then when longjmp is called from g3,
longjmp removes from the stack all information (local variables, return addresses,
and so forth) due to calls to functions g1 through g3. The environment buffer saves
the information needed for stack restoration.
If you do not initialize env before calling longjmp, or if you call longjmp after the
function containing its corresponding setjmp has completed execution, the result of
the call to longjmp is unpredictable. If it can detect the error, longjmp returns to its
caller.
The call to setjmp and all calls to longjmp with the same environment buffer resume
execution at the same place: following the call to setjmp. You can distinguish
between these different cases only if you pass different values of val. That is,
execution resumes at the same place, but with different return values.
In order for the calling environment to be properly restored, you must call setjmp
from simple expressions only. An expression is simple if the setjmp call is the sole
term, or if the result of the setjmp call is compared with a constant expression.
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
longlong_to_dec (supplementary)
longlong_to_dec (supplementary)
The longlong_to_dec function converts a long long value to an SQL DECIMAL value
and stores the converted value in a C array of decimal.
#include <sqlh>
int longlong_to_dec(long long ll_val, decimal *dec_ary,
int ary_size, int sign_type);
ll_val
specifies the long long value to convert.
dec_ary
points to the first character of the decimal array where longlong_to_dec stores the
converted DECIMAL value.
ary_size
specifies the size (in characters) of the array denoted by *dec_ary.
sign_type
specifies what type of sign representation to use for the converted DECIMAL value.
The valid sign_type values are:
0
Convert to an unsigned DECIMAL value.
1
Convert to a DECIMAL value with an embedded leading sign.
2
Convert to a DECIMAL value with a separate leading sign character.
3
Convert to a DECIMAL value with an embedded trailing sign.
4
Convert to a DECIMAL value with a separate trailing sign character.
Return Value
is zero if the conversion is successful; otherwise, longlong_to_dec returns one of
these status codes:
1
Indicates that significant digits of ll_val were truncated in the conversion; that
is, the converted value exceeded the specified size of the decimal array.
2
Indicates that the ary_size argument had an invalid value. An invalid value is
less than zero or greater than 19.
3
Indicates that ll_val was negative, but sign_type was 0 (a request for
conversion to an unsigned DECIMAL value).
4
Indicates that the sign_type argument had an invalid value.
Guardian TNS C Library Calls Reference Manual—128833
3 -109
longlong_to_dec (supplementary)
Reference to Library Calls
Usage Guidelines
•
•
3- 110
When longlong_to_dec returns a nonzero value to indicate that the conversion was
not successful, the value stored in *dec_ary is undefined.
For more information regarding the representation of SQL DECIMAL values in
C arrays of decimal, refer to the NonStop SQL/MP Programming Manual for C.
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
lseek (supplementary)
lseek (supplementary)
The lseek function sets the file-position indicator of a byte-addressable file opened for
alternate I/O.
#include <fcntlh>
long lseek(int file_des, long pos, int pos_base);
file_des
is the descriptor denoting a file opened for alternate I/O.
pos
is a long value specifying the desired position.
pos_base
specifies whether pos denotes an offset from the beginning, current position, or end
of the file. You specify the pos_base by using one of the following object-like
macros:
•
•
•
SEEK_SET indicates that the offset is relative to the beginning of the file.
SEEK_CUR indicates that the offset is relative to the current file position.
SEEK_END indicates that the offset is relative to the end of the file.
Return Value
is the new file position if the operation is successful or -1 if an error occurs.
Usage Guidelines
•
The lseek function has no effect if the file is a device (a terminal, for example).
Example
In this example, the lseek function sets the file-position indicator to the beginning of the
file:
#include <fcntlh>
int filedes, pos_base;
long status, pos;
filedes = open ("$a.b.c");
/* ... */
pos = 0;
pos_base = SEEK_SET;
status = lseek(filedes, pos, pos_base);
Guardian TNS C Library Calls Reference Manual—128833
3 -111
malloc
Reference to Library Calls
malloc
The malloc function allocates memory starting on a word boundary.
#include <stdlibh>
void *malloc(size_t nbytes);
nbytes
specifies the number of bytes to allocate.
Return Value
points to the allocated memory if the operation is successful; otherwise, malloc
returns the pointer value NULL.
Usage Guidelines
•
•
•
Note that malloc returns a pointer of type void, which is compatible with any pointer
type. However, if you explicitly specify the intended type using a cast expression,
your code will be more maintainable and readable. Both of the following examples
show the intended type using a cast expression.
If you have compiled your program for the large-memory model, the malloc
function will automatically enlarge the extended data segment when necessary.
Each call to the malloc function should have a corresponding call to the free
function to avoid blocks of allocated memory that are no longer in use.
Examples
1. This example allocates memory for a char array of 10 elements:
#include <stdlibh>
char *ptr;
/* ... */
ptr = (char *)malloc(10*sizeof(char));
2. This example allocates memory for an int array of 5 elements:
#include <stdlibh>
int *ptr;
/* ... */
ptr = (int *)malloc(5*sizeof(int));
3- 112
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
_max (supplementary)
_max (supplementary)
The _max macro expands to the greater of its two arguments.
#include <stdlibh>
<arith_type> _max(<arith_type> expr1, <arith_type> expr2);
<arith_type>
is the type of expr1, expr2, and the return value. It can be any arithmetic type.
expr1
is an expression.
expr2
is an expression of the same type as expr1.
Return Value
is the numerically greater of the two arguments, expr1 and expr2.
Usage Guidelines
•
Because _max is a macro, you should avoid specifying expressions with side effects
as arguments.
Example
This example prints “The maximum number is 7.”:
#include <stdlibh>
#include <stdioh>
int main(void)
{
double r, x, y;
x = 5.0;
y = 7.0;
r = _max(x, y);
printf("The maximum number is %f.", r);
}
Guardian TNS C Library Calls Reference Manual—128833
3 -113
mblen
Reference to Library Calls
mblen
The mblen function determines the length in bytes of a multibyte character.
#include <stdlibh>
int mblen(const char *s, size_t n);
s
points to the multibyte character.
n
defines the maximum length in characters of the multibyte character.
Return Value
If s is a null pointer, the return value is 0.
If s is not a null pointer, the return value is:
0
if s points to a null character
1
if s points to a one-byte character, different from null
2
if s points to the first byte of a two-byte character
-1
if none of the above is true
Usage Guidelines
•
3- 114
The behavior of the mblen function is affected by the LC_CTYPE category of the
current locale.
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
mbstowcs
mbstowcs
The mbstowcs function converts a sequence of multibyte characters to a corresponding
sequence of wide characters.
#include <stdlibh>
size_t mbstowcs(wchar_t *pwcs, const char *s, size_t n);
pwcs
points to the array that will contain the sequence of wide characters.
s
points to the array that contains the sequence of multibyte characters. No multibyte
characters that follow a null character will be examined or converted. The multibyte
characters pointed to by s must be in the initial shift state.
n
specifies the maximum number of bytes that will be modified in the array pointed to
by pwcs.
Return Value
(size_t) -1 if an invalid multibyte character is encountered.
Otherwise, the function returns the number of array elements copied to pwcs. If a
null terminator is present, it is not included in this count.
Usage Guidelines
•
The mbstowcs function is affected by the LC_CTYPE category of the current locale.
Guardian TNS C Library Calls Reference Manual—128833
3 -115
mbtowc
Reference to Library Calls
mbtowc
The mbtowc function converts a multibyte character to a wide character. The argument s
points to the beginning of a multibyte character that is not more than n characters long.
The function converts the character to its wide character representation, storing the result
in the variable pointed to by pwc, if pwc is not a null pointer.
#include <stdlibh>
int mbtowc(wchar_t *pwc, const char *s, size_t n);
pwc
points to the variable of type wchar_t that will contain the wide character encoding.
s
points to the multibyte character.
n
defines the maximum length in bytes of the array pointed to by s that the mbtwoc
function will examine.
Return Value
If s is a null pointer,.the return value is 0.
If s is not a null pointer, the return value is:
0
if s points to a null character
1
if s points to a one-byte character, different from null
2
if s points to the first byte of a two-byte character
-1
if none of the above is true
Usage Guidelines
•
3- 116
The behavior of the mbtowc function is affected by the LC_CTYPE category of the
current locale.
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
memchr
memchr
The memchr function searches for the first occurrence of a byte value within a block of
memory.
#include <stringh>
void *memchr(const void *block, int value, size_t
block_size);
block
points to the block to search.
value
is the value to search for; it is converted to an unsigned char before the search.
block_size
is the size in bytes of the block to search.
Return Value
points to the first occurrence of value if it is found; otherwise, memchr returns the
pointer value NULL.
Guardian TNS C Library Calls Reference Manual—128833
3 -117
memcmp
Reference to Library Calls
memcmp
The memcmp function performs an unsigned byte comparison of two blocks of memory.
#include <stringh>
int memcmp(const void *block1, const void *block2, size_t
cmp_count);
block1
points to the first block to compare.
block2
points to the second block to compare.
cmp_size
is the number of bytes to compare.
Return Value
is zero if the two blocks are equal, a negative value if *block1 is less than *block2,
or a positive value if *block1 is greater than *block2.
Usage Guidelines
•
3- 118
The memcmp function treats the two blocks as arrays of unsigned char.
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
memcpy
memcpy
The memcpy function copies one block of memory to another. If the destination block
overlaps the source block, memcpy does not preserve the data in the overlapping portion
of the source block.
#include <stringh>
void *memcpy(void *dest_blk, const void *source_blk,
size_t copy_count);
dest_blk
points to the block to copy data to.
source_blk
points to the block to copy data from.
copy_count
is the number of bytes to copy.
Return Value
is dest_blk.
Guardian TNS C Library Calls Reference Manual—128833
3 -119
memmove
Reference to Library Calls
memmove
The memmove function moves one block of memory to another. If the destination block
overlaps the source block, memmove preserves the data in the overlapping portion of the
source block. Consequently, memmove is slower than memcpy.
#include <stringh>
void *memmove(void *dest_blk, const void *source_blk,
size_t move_count);
dest_blk
points to the block to move data to.
source_blk
points to the block to move data from.
move_count
is the number of bytes to move.
Return Value
is dest_blk.
memset
The memset function fills a block of memory with a given byte value.
#include <stringh>
void *memset(void *block, int value, size_t block_size);
block
points to the block to fill.
value
is the value to fill *block with; it is converted to an unsigned char.
block_size
is the size in bytes of the block to fill.
Return Value
is block.
3- 120
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
memswap (supplementary)
memswap (supplementary)
The memswap function exchanges the contents of two non-overlapping blocks of
memory.
#include <stringh>
void memswap(void *blk1, void *blk2, size_t swap_count);
blk1
points to one of the blocks to swap.
blk2
points to the other block to swap.
swap_count
is the number of bytes to swap.
Return Value
none.
Guardian TNS C Library Calls Reference Manual—128833
3 -121
_min (supplementary)
Reference to Library Calls
_min (supplementary)
The _min macro expands to the lesser of its two arguments.
#include <stdlibh>
<arith_type> _min(<arith_type> expr1, <arith_type> expr2);
<arith_type>
is the type of expr1, expr2, and the return value. It can be any arithmetic type.
expr1
is an expression.
expr2
is an expression of the same type as expr1.
Return Value
is the numerically lesser of the two arguments, expr1 and expr2.
Example
This example prints “The minimum number is 5.000000”:
#include <stdlibh>
#include <stdioh>
int main(void)
{
double r, x, y;
x = 5.0;
y = 7.0;
r = _min(x, y);
printf("The minimum number is %f.", r);
}
3- 122
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
mktime
mktime
The mktime function converts the broken down local time in the structure pointed to by
timeptr into the corresponding calendar time.
#include <time.h>
time_t mktime(struct tm *timeptr);
timeptr
points to the structure that contains the broken-down time, expressed as local time.
This structure is of type struct tm.
Return Value
is the specified calendar time encoded as a value of type time_t. If the calendar time
cannot be represented, the function returns the value (time_t)-1.
Usage Guidelines
•
The structure pointed to by timeptr is of type struct tm. The structure type struct tm
is defined in the header timeh and has the following members:
struct tm{
int tm_sec;
int tm_min;
int tm_hour;
int tm_mday;
int tm_mon;
int tm_year;
int tm_wday;
int tm_yday;
int tm_isdst;
};
/*
/*
/*
/*
/*
/*
/*
/*
/*
seconds after the minute: [0, 61]*/
minutes after the hour: [0, 59] */
hours since midnight: [0, 23]
*/
day of the month: [1, 31]
*/
months since January: [0, 11]
*/
years since 1900
*/
days since Sunday; [0, 6]
*/
days since January 1: [0, 365]
*/
Daylight Savings Time flag
*/
Note that the flag tm_isdst is positive if Daylight Savings Time is in effect, zero if it
is not, and negative if the information is not available.
•
•
For the purpose of the computation, the tm_wday and tm_yday members of the
structure are disregarded. On successful completion of the computation, the values
of the tm_wday and tm_yday members of the structure are set appropriately, and the
other members of the structure might be overwritten with an equivalent set of values
in which each member lies within its normal range. The final value of tm_mday is
not set until tm_mon and tm_year are determined.
You get Wed Dec 31 23:59:59 1969 for the date if you enter a value out of range for:
tm_sec, tm_min, tm_hour, tm_mday, tm_mon, or tm_year.
Guardian TNS C Library Calls Reference Manual—128833
3 -123
mktime
Reference to Library Calls
Example
This example finds the date 1000 days from now.
#include <timeh>
#include <stdioh>
struct tm
time_t
*timeptr;
now, later;
int main(void)
{
now = time(NULL);
timeptr = localtime(&now);
timeptr -> tm_mday += 1000;
later = mktime(timeptr);
printf("\n1000 days from now: %s\n", ctime(&later));
}
3- 124
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
modf
modf
The modf function splits a floating-point number into integral and fractional parts.
#include <mathh>
double modf(double expr, double *int_part);
expr
is an expression of type double.
int_part
points to the variable of type double where modf stores the integral part of expr.
Return Value
is the fractional part of expr.
Example
This example prints “The fractional part is 0.234000. The integral part is 1.000000.”:
#include <stdioh>
#include <mathh>
int main(void)
{
double r, x, y;
x = 1.234;
r = modf(x, &y);
printf("The fractional part is %f. ", r);
printf("The integral part is %f.\n", y);
}
Guardian TNS C Library Calls Reference Manual—128833
3 -125
movmem (supplementary)
Reference to Library Calls
movmem (supplementary)
The movmem function moves a block of memory. It performs the move so that data is
preserved even if the source block overlaps the destination block.
#include <memoryh>
void movmem(char *blk_ptr, char *dest_ptr, size_t nbytes);
blk_ptr
points to the beginning of the block.
dest_ptr
points to the destination where movmem moves the block.
nbytes
specifies the number of bytes to move.
Return Value
none.
Example
This example moves 100 bytes to dest:
#include <memoryh>
char blk[100];
char dest[100];
/* ... */
movmem(blk, dest, 100);
__ns_backup_fopen (supplementary)
For active backup process pairs, the __ns_backup_fopen function performs a backup
open for a file that was opened in the primary process using ANSI-model I/O.
#include <nonstoph>
FILE *__ns_backup_fopen(
__ns_std_io_file_open_state *file_open_state);
file_open_state
points to a variable that stores the file open state information.
3- 126
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
__ns_backup_fopen (supplementary)
Return Value
0 if the operation is successful, -1 if an error occurs.
Usage Guidelines
•
•
•
•
•
•
•
•
•
•
•
•
This function is called from the backup process to perform a backup open of the file.
Before calling this function, the primary process must have first called the
__ns_fget_file_open_state function to retrieve the file open state information and
sent the state information through the $RECEIVE facility to the backup process.
The variable containing the file state information, not the pointer to the variable,
must be sent through the $RECEIVE facility from the primary process to the backup
process.
The backup file open does not perform any fopen function access_mode actions that
create or truncate a file. File creation and truncation actions are not necessary
because these actions were performed by the initial fopen call in the primary
process.
If an error occurs, errno is set to one of the following:
ENOIMEM, if insufficient memory is available.
An fopen function error code, if an error occurs on the file open.
A Guardian file system error code, if a file system error occurs. (Error 12 indicates
the backup open cannot obtain the same file number assigned to the primary open.)
An error detected in the backup process is not automatically sent to the primary
process. User code must handle such processing.
The only meaningful operations on file open state information are retrieving with the
__ns_fget_file_open_state function, starting a backup file open with the
__ns_backup_open function, and copying with an assignment statement or a copy
function from the C run-time library. The results of manipulating components of the
file open state information are undefined.
In addition to either the CLARGE or CWIDE library file, you must bind the
CNONSTOP library file into programs that use this function.
This function can only be used in the Guardian environment.
Refer to the Guardian Programmer’s Guide for complete details on fault-tolerant
programming in C.
Guardian TNS C Library Calls Reference Manual—128833
3 -127
__ns_fget_file_open_state (supplementary)
Reference to Library Calls
__ns_fget_file_open_state (supplementary)
The __ns_fget_file_open_state function returns the file open state information for a file
open for ANSI I/O.
#include <nonstoph>
long __ns_fget_file_open_state(
FILE *stream,
__ns_std_io_file_open_state *file_open_state);
stream
denotes a file opened for ANSI I/O.
file_open_state
points to a variable that stores the file open state information.
Return Value
0 if the operation is successful, -1 if an error occurs.
Usage Guidelines
•
•
•
•
•
•
•
•
•
3- 128
This function is called from the primary process to retrieve the current file open state
information. The primary process sends the state information through the
$RECEIVE facility to the backup process. The backup process calls the
__ns_backup_fopen function to perform a backup open of the file.
The variable containing the file state information, not the pointer to the variable,
must be sent through the $RECEIVE facility from the primary process to the backup
process.
If an error occurs, errno is set to one of the following:
ENONSTOP, if the file specified in the stream argument is not open.
A Guardian file system error code, if a file system error occurs.
The only meaningful operations on file open state information are retrieving with the
__ns_fget_file_open_state function, starting a backup file open with the
__ns_backup_fopen function, and copying with an assignment statement or a copy
function from the C run-time library. The results of manipulating components of the
file open state information are undefined.
In addition to either the CLARGE or CWIDE library file, you must bind the
CNONSTOP library file into programs that use this function.
This function can only be used in the Guardian environment.
Refer to the Guardian Programmer’s Guide for complete details on fault-tolerant
programming in C.
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
__ns_fget_file_state (supplementary)
__ns_fget_file_state (supplementary)
The __ns_fget_file_state function returns the state information for a file open for ANSI
I/O.
#include <nonstoph>
long __ns_fget_file_state(
FILE *stream,
__ns_std_io_file_state *file_state);
stream
denotes a file opened for ANSI I/O.
file_state
points to a variable that stores the file state information.
Return Value
0 if the operation is successful, -1 if an error occurs.
Usage Guidelines
•
•
•
•
•
•
This function is called from the primary process to retrieve the current file state
information. The primary process sends the state information through the
$RECEIVE facility to the backup process. The backup process calls the
__ns_fset_file_state function to update its state information for the file.
The variable containing the file state information, not the pointer to the variable,
must be sent through the $RECEIVE facility from the primary process to the backup
process.
If the file specified in the stream argument is not open, errno is set to ENONSTOP.
The only meaningful operations on file state information are retrieving with the
__ns_fget_file_state function, setting with the __ns_fset_file_state function, and
copying with an assignment statement or a copy function from the C run-time
library. The results of manipulating components of the file state information are
undefined.
The buffer for file operations is not part of the file state. This affects the input and
output streams:
For input streams, the file position is a component of the file state. The
__ns_fset_file_state function updates the file position for the backup process to the
file position of the primary process at the time the __ns_fget_file_state function was
called. Thus, buffering is not an issue for an input stream from a disk device. For all
other input streams, buffered but unread input is lost. For these nondisk input
streams, you can disable buffering with either the setvbuf or setnbuf function, ignore
the lost information, or manage the buffer yourself.
Guardian TNS C Library Calls Reference Manual—128833
3 -129
__ns_fopen_special (supplementary)
•
•
•
•
•
•
•
Reference to Library Calls
For output streams, a call to a write function in user code might leave a partially
filled, unflushed buffer. To ensure that the buffer is flushed, you can:
Perform a flush operation, such as a call to the fflush function, prior to calling the
__ns_fget_file_state function.
Ignore the effects of unflushed buffers, if the unflushed buffer contents are not
critical to the application.
Disable buffering with the setvbuf or setnbuf function.
In addition to either the CLARGE or CWIDE library file, you must bind the
CNONSTOP library file into programs that use this function.
This function can only be used in the Guardian environment.
Refer to the Guardian Programmer’s Guide for complete details on fault-tolerant
programming in C.
__ns_fopen_special (supplementary)
The __ns_fopen_special function opens a file for ANSI-model I/O and allows a sync
depth to be specified.
#include <nonstoph>
FILE *__ns_open_special(
char *file_name,
char *access_mode,
short sync_depth);
file_name
points to a string containing a valid file name.
*access_mode
points to a string that specifies how you want to access the file. The possible values
for *access_mode are described under “Usage Guidelines.”
sync_depth
specifies the number of nonretryable write requests whose completion must be
remembered by the file system. sync_depth must conform to the operating system
limit of a value between zero and fifteen.
Return Value
points to the FILE structure denoting the opened file if the operation is successful;
otherwise, the function returns the pointer value NULL.
3- 130
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
__ns_fopen_special (supplementary)
Usage Guidelines
•
•
If you want to specify the sync depth, call the __ns_fopen_special function from
primary process instead of the fopen function. Otherwise, __ns_fopen_special
operates the same as the fopen function.
For buffered file operations, a call to a write function in user code does not
necessarily correspond to one write operation at the operating system level where
the sync-depth value is meaningful. An operating system write operation is
performed in the following situations:
•
•
A flush operation is performed, such as a call to the fflush, fclose, or exit
function.
The buffer is filled.
You can disable buffering with the setvbuf or setnbuf function.
•
•
If a device does not support the sync-id mechanism and a sync_depth value is
specified, a value of one (1) is used for sync_depth.
The possible values of the string *access_mode are:
“r”
Open an existing text file for read-only access.
“w”
Create a text file (or truncate an existing text file to length zero) and open
it for write-only access.
“a”
Create a text file (or open an existing text file) and open it for append
(write at the end of the file) access.
“r+”
Open an existing text file for update access (reading and writing).
“w+”
Create a text file (or truncate an existing text file to length zero) and open
it for update access.
“a+”
Create a text file (or open an existing text file) and open it for update
access with writing at the end of the file.
“rb”
Open an existing binary file for read-only access.
“wb”
Create a binary file (or truncate an existing binary file to length zero) and
open it for write-only access.
“ab”
Create a binary file (or open an existing binary file) and open it for
append (write at the end of the file) access.
“rb+”
Open an existing binary file for update access (reading and writing).
“wb+
”
Create a binary file (or truncate an existing binary file to length zero) and
open it for update access.
“ab+”
Create a binary file (or open an existing binary file) and open it for
update access with writing at the end of the file.
If you attempt to open a file in read mode and the file does not exist or cannot be
read, __ns_fopen_special fails, returning the pointer value NULL.
Guardian TNS C Library Calls Reference Manual—128833
3 -131
__ns_fset_file_state (supplementary)
Reference to Library Calls
When you open a file in append mode, the file-position indicator is set to the end of
the file before each write operation, regardless of previous positioning.
•
If you include a system name in the file name, you must precede the system name
with two backslashes instead of one because backslash is an escape character in C.
For example, to open the file \sys.$vol.svol.file, you would use the C string:
"\\sys.$vol.svol.file"
•
•
•
•
•
•
•
•
Unless you include b in the access string, the file is opened as a text file.
If the file does not already exist, __ns_fopen_special creates a C binary file if you
include b in the access string; otherwise, it creates an Edit file.
The default number of secondary extents for files created by __ns_fopen_special is
16.
The default number of maxextents for files created by __ns_fopen_special is 500.
If an error occurs, errno is set to one of the following:
•
•
•
EINVAL, if an invalid argument is specified.
ENOIMEM, if insufficient memory is available.
An fopen function error code, if an error occurs on the file open.
In addition to either the CLARGE or CWIDE library file, you must bind the
CNONSTOP library file into programs that use this function.
This function can only be used in the Guardian environment.
Refer to the Guardian Programmer’s Guide for complete details on fault-tolerant
programming in C.
__ns_fset_file_state (supplementary)
The __ns_fset_file_state function sets the state information for an ANSI I/O file.
#include <nonstoph>
long __ns_fset_file_state(
FILE *stream,
__ns_std_io_file_state *file_state);
stream
denotes a file opened for ANSI I/O.
file_state
points to a variable that stores the file state information.
3- 132
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
__ns_fset_file_state (supplementary)
Return Value
0 if the operation is successful, -1 if an error occurs.
Usage Guidelines
•
•
•
•
•
This function is called from the backup process to update its state information for
the file. Before calling this function, the primary process must have first called the
__ns_fget_file_state function to retrieve the file state information and sent the state
information through the $RECEIVE facility to the backup process.
The variable containing the file state information, not the pointer to the variable,
must be sent through the $RECEIVE facility from the primary process to the backup
process.
If the file specified in the stream argument is not open, errno is set to ENONSTOP.
The only meaningful operations on file state information are retrieving with the
__ns_fget_file_state function, setting with the __ns_fset_file_state function, and
copying with an assignment statement or a copy function from the C run-time
library. The results of manipulating components of the file state information are
undefined.
The buffer for file operations is not part of the file state. This affects the input and
output streams:
•
•
For input streams, the file position is a component of the file state. The
__ns_fset_file_state function updates the file position for the backup process to
the file position of the primary process at the time the __ns_fget_file_state
function was called. Thus, buffering is not an issue for an input stream from a
disk device. For all other input streams, buffered but unread input is lost. For
these nondisk input streams, you can disable buffering with either the setvbuf or
setnbuf function, ignore the lost information, or manage the buffer yourself.
For output streams, a call to a write function in user code might leave a partially
filled, unflushed buffer. To ensure that the buffer is flushed, you can:
•
•
•
•
•
•
Perform a flush operation, such as a call to the fflush function, prior to
calling the __ns_fget_file_state function.
Ignore the effects of unflushed buffers, if the unflushed buffer contents are
not critical to the application.
Disable buffering with the setvbuf or setnbuf function
In addition to either the CLARGE or CWIDE library file, you must bind the
CNONSTOP library file into programs that use this function.
This function can only be used in the Guardian environment.
Refer to the Guardian Programmer’s Guide for complete details on fault-tolerant
programming in C.
Guardian TNS C Library Calls Reference Manual—128833
3 -133
__ns_start_backup (supplementary)
Reference to Library Calls
__ns_start_backup (supplementary)
The __ns_start_backup function creates a backup process for the primary process.
#include <nonstoph>
_extensible long __ns_start_backup(
short *error_detail,
short backup_cpu,
short *backup_process_handle,
char *backup_hometerm,
short backup_debug_options);
error_detail
is an optional output parameter that receives the error detail information from the
Guardian procedure PROCESS_CREATE_.
backup_cpu
is an optional input parameter that specifies the number of the CPU in which to start
the backup process. If this parameter is omitted or its value is -1, the operating
system selects a CPU.
backup_process_handle
is an optional output parameter that receives the process handle of the backup
process.
backup_hometerm
is an optional input parameter that points to a string naming a home terminal for the
backup process. If this parameter is omitted, the backup process has the same home
terminal as the primary process.
backup_debug_options
is an optional input parameter that specifies debugging options for the backup
process. backup_debug_options corresponds to the debug-options parameter of the
Guardian procedure PROCESS_CREATE_. Refer to the Guardian Procedure Calls
Reference Manual for details.
Return Value
0 if the operation is successful, -1 or a positive value if an error occurs.
3- 134
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
__ns_start_backup (supplementary)
Usage Guidelines
•
•
This function is called from the primary process to create and initialize the backup
process.
To create the backup process, __ns_start_backup:
•
•
•
•
•
•
•
•
•
•
Returns the process handle of the backup process, if the process started
successfully.
To initialize the backup process, __ns_start_backup:
•
•
Starts the backup process with a call to the PROCESS_CREATE_ Guardian
procedure.
Sends to the backup process the same startup, ASSIGN, and PARAM messages
received by the primary process.
Calls __ns_fget_file_open_state from the primary process to retrieve the file
open state information for the standard input, output, and error files (stdin,
stdout, stderr).
Sends the file open state information from the primary process to the backup
process using the $RECEIVE facility. The backup process then performs a
backup open of the standard files using the file open state information received
the primary process. The sync depth of the standard files is 1.
Only the standard files have backup opens performed. Other files opened by the
primary process must be explicitly opened in the backup process by calls to
__ns_backup_open.
The file states of the standard files in the backup process are not automatically set to
the corresponding file states in the primary process. If operations have been
performed on a standard file before __ns_start_backup has been called, you must
call __ns_fget_file_state and __ns_fset_file_state to retrieve and set the file state for
the standard files.
The backup process has the same swap volume and subvolume as the primary
process.
Use the backup_hometerm and backup_debug_options parameters to help test and
debug process pairs.
If an error occurs during process creation, the return value is a positive value that
corresponds to a PROCESS_CREATE_ error code. If you supplied an error_detail
parameter, it contains the PROCESS_CREATE_ error subcode. Refer to the
Guardian Procedure Calls Reference Manual for details.
If an error occurs during process initialization, the return value is -1 and errno is set
to either of the following:
•
•
A Guardian file system error code, if a file system error occurs.
ENONSTOP, for any other error condition.
Guardian TNS C Library Calls Reference Manual—128833
3 -135
offsetof
•
•
•
Reference to Library Calls
In addition to either the CLARGE or CWIDE library file, you must bind the
CNONSTOP library file into programs that use this function.
This function can only be used in the Guardian environment.
Refer to the Guardian Programmer’s Guide for complete details on fault-tolerant
programming in C.
offsetof
The offsetof macro expands to the offset in bytes of a structure member from the start of
its structure.
#include <stddefh>
size_t offsetof(struct-type, struct-member);
struct-type
is a type name denoting a structure type.
struct-member
is an identifier denoting a member of the structure type struct-type.
Return Value
is the offset in bytes of the member struct-member from the beginning of the
structure type struct-type.
Usage Guidelines
•
3- 136
The offsetof function can be used in static initialization of aggregates.
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
open (supplementary)
open (supplementary)
The open function opens a file for alternate I/O.
#include <fcntlh>
int open(char *file_name, int flags, [int security],
[int depth], [int pext], [int sext]);
file_name
points to a string containing a valid Guardian file name.
flags
is an integer value specifying the attributes of the file. Possible attribute values are
described under “Usage Guidelines.”
security
specifies the security setting. See the FUP SECURE command description of integer
encoding in the FUP Reference Manual for more information.
depth
is analogous to the sync-or-receive-depth parameter of the FILE_OPEN_ system
procedure. See the Guardian Procedure Calls Reference Manual for more
information. If you do not specify depth, then open uses the value 1.
pext
specifies the number of pages (2048-byte blocks) in the primary extent; it must be in
the range 1 through 65,535. If you omit pext, then open uses the value 2.
sext
specifies the number of pages in each of the secondary extents; it must be in the
range 1 through 65,535. If you omit sext, then open uses the value 4.
Return Value
is a descriptor denoting the newly opened file if the operation is successful or -1 if
an error occurs.
Guardian TNS C Library Calls Reference Manual—128833
3 -137
open (supplementary)
Reference to Library Calls
Usage Guidelines
•
•
The following macros specify the possible attributes for flags. Select the attributes
that represent attributes of the file to be opened. To specify more than one option,
use the bit-wise OR operator (|).
Macro
Description
O_APPEND
Sets the file-position indicator to the end of the file before each write.
O_BINARY
Opens the file for binary I/O.
O_CREAT
Creates the file if it does not exist.
O_EXCL
Causes open to fail if the file already exists; it must be used in
conjunction with O_CREAT.
O_EXCLUSIVE
Indicates that the opening process cannot allow any simultaneous
access of any kind to the file. Therefore, any further attempts to open
the file, while the file is open, are rejected. Likewise, if a file is
already open, any attempt to open the file with exclusive access is
rejected.
O_PROTECTED
Indicates that the opening process can allow simultaneous read access
to the file but cannot allow simultaneous write access to the file.
Therefore, while the file is opened with protected access, any further
attempts to open the file with read-write or write-only access mode
are rejected. Likewise, if the file is already open with read-write or
write-only access mode, any attempt to open it with protected access
is rejected. However, simultaneous accessors can open a file with
read-only access mode.
O_RDONLY
Opens the file for read-only access.
O_RDWR
Opens the file for read-write access.
O_SHARED
Indicates that the opening process can allow simultaneous read and/or
write access by other processes to the file.
O_SYSMSG
For internal library use only.
O_TEXT
Opens the file for text I/O.
O_TRUNC
Truncates the file to a length of zero if the file exists.
O_WRONLY
Opens the file for write-only access.
In a C-series system, the open function opens a file with the default exclusion mode
PROTECTED ACCESS, if the flags O_SHARED and O_EXCLUSIVE are not
specified in the call. In the D-series system, the default exclusion mode is
EXCLUSIVE ACCESS.
To work around this C-series and D-series discrepancy, if you want to open a file
with the exclusion mode PROTECTED ACCESS, modify existing C programs to
specify the O_PROTECTED flag in the open function
•
•
3- 138
The open function ignores security, pext, and sext for files that already exist.
If you open a file that is neither an Edit file nor a terminal and you don’t specify
O_TEXT, then open opens the file for binary access.
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
•
•
•
perror
This function sets the file-position indicator to the start of the file (assuming that the
file is successfully opened).
For more information regarding file extents and pages, refer to the ENSCRIBE
Programmer’s Guide.
This manual does not include a discussion about waited I/O and nowait I/O because
the C programming language does not provide this capability. For waited and nowait
I/O, you must use Guardian system procedures.
Example
This example opens a file named $a.b.c for reading and writing:
#include <fcntlh>
int filedes;
filedes = open("$a.b.c", O_RDWR);
perror
The perror function prints the textual error message corresponding to the current value
of errno, optionally preceded by a specified string, to the standard error file, stderr.
#include <stdioh>
void perror(const char *user_text);
user_text
points to a string or is the pointer value NULL.
Return Value
none.
Usage Guidelines
•
The form of the error message that perror prints is:
1. The string pointed to by user_text (if user_text is a nonnull pointer).
2. A textual message corresponding to the current value of errno. This message is
the same as the string strerror returns for the given value of errno.
3. A newline character.
Guardian TNS C Library Calls Reference Manual—128833
3 -139
pow
Reference to Library Calls
pow
The pow function computes the value of its first argument raised to the power of its
second argument.
#include <mathh>
double pow(double expr1, double expr2);
expr1
is an expression of type double.
expr2
is an expression of type double, specifying the power to which to raise expr1.
Return Value
is the value of expr1 raised to the expr2 power (that is, expr1expr2). If expr1 is zero
and expr2 is less than or equal to zero, or if expr1 is negative and expr2 is not an
integral value, pow returns -HUGE_VAL and sets errno to EDOM (a domain error).
In addition, pow returns HUGE_VAL if a positive overflow occurs, -HUGE_VAL if
a negative overflow occurs or zero if underflow occurs. In each of these cases, pow
also sets errno to ERANGE (a range error).
Example
This example prints “2.000000 to the power of 3.000000 is 8.000000.”:
#include <mathh>
#include <stdioh>
int main(void)
{
double r, x, y;
x = 2.0;
y = 3.0;
r = pow(x, y);
printf("%f to the power of %f is %f.", x, y, r);
}
3- 140
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
printf
printf
The printf function writes formatted data to the standard output file.
#include <stdioh>
int printf(const char *format, [expr...]);
format
points to a string that contains characters and conversion specifiers. Refer to
“fprintf” on page 3-51 for a description of format and conversion specifiers.
expr...
is the list of arguments to be formatted using the conversion specifiers in *format.
Return Value
is the number of characters output if the operation is successful; otherwise, printf
returns a negative value.
Usage Guidelines
•
To print a percent sign, you must precede it with a percent sign; for example:
printf("Stock went up %d%%\n", increase);
•
When the converted printf argument has fewer characters than the specified field
width, printf uses blanks to pad out the extra space. To request padding with zeroes
instead of blanks, precede the field width with a zero; for example:
printf("%3d%3s\n", 5, "A");
printf("%03d%03s\n", 5, "A");
produces the following:
5 A
00500A
Guardian TNS C Library Calls Reference Manual—128833
3 -141
printf
Reference to Library Calls
Example
In this example, printf fetches two arguments, formats them as fixed-decimal floatingpoint numbers, and prints “The square root of 25.000000 is 5.000000”:
#include <stdioh>
#include <mathh>
int main(void)
{
double r, x;
x = 25;
r = sqrt(x);
printf("The square root of %f is %f\n", x, r);
}
3- 142
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
putc
putc
The putc function writes a character to a file opened for ANSI I/O.
#include <stdioh>
int putc(int character, FILE *stream);
character
specifies the character to be written.
stream
denotes a file opened for ANSI I/O.
Return Value
is the character written if the operation is successful; otherwise, putc returns the
value EOF.
Usage Guidelines
•
•
The putc function might be implemented as a macro in a future release.
Consequently, you should use fputc rather than putc if you are concerned about the
amount of memory in the macro expansion or about side effects.
When using putc to write to an Edit file, you must terminate each line with a
newline character. Between newline characters you can write up to 239 characters,
which is the maximum length of a line for Edit files.
Example
In this example, the putc function writes the letter “a” to $a.b.c:
#include <stdioh>
FILE *fp;
int status;
int c;
fp = fopen("$a.b.c ", "w");
c = 'a';
/* ... */
status = putc(c, fp);
Guardian TNS C Library Calls Reference Manual—128833
3 -143
putchar
Reference to Library Calls
putchar
The putchar function writes a character to the standard output file.
#include <stdioh>
int putchar(int character);
character
specifies the character to be written.
Return Value
is the character written if the operation is successful; otherwise, putchar returns the
value EOF.
Usage Guidelines
•
The putchar function might be implemented as a macro in a future release.
Example
This example writes the letter “a” to the standard output file:
#include <stdioh>
int status;
int c;
c = 'a';
status = putchar(c);
3- 144
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
putenv
putenv
The putenv function sets the value of a run-time parameter from the environment array.
#include <stdlibh>
int putenv(const char *env_parm);
env_parm
points to a string of the form name=value. name is the run-time parameter to set and
value is the value to set the parameter to. This string must be in uppercase. Possible
values for *env_parm are described under “Usage Guidelines.”
Return Value
is zero if putenv is successful
Usage Guidelines
•
The environment array always contains the following four run-time parameters, as
you would specify them in *env_parm:
"STDIN"
Gives the file name of the standard input file stdin.
"STDOUT"
Gives the file name of the standard output file stdout.
"STDERR"
Gives the file name of the standard error file stderr.
"DEFAULTS"
Gives the default volume and subvolume names used to qualify
partial file names.
In addition to these four parameters, the environment array contains values for all
user-defined parameters (PARAMs) active when your C program starts.
•
•
To use this routine, you must specify the _XOPEN_SOURCE feature test macro for
the header file stdlibh.
If the main routine of a mixed-language program is not written in C, the value of the
SAVE-ENVIRONMENT PARAM must be set to ON to use the putenv function.
Refer to the Common Run-Time Environment (CRE) Programmer’s Guide for more
information.
Guardian TNS C Library Calls Reference Manual—128833
3 -145
puts
Reference to Library Calls
puts
The puts function writes a string to the standard output file.
#include <stdioh>
int puts(const char *str_ptr);
str_ptr
points to an array of characters.
Return Value
is zero if the call is successful. Otherwise, a nonzero value is returned.
Usage Guidelines
•
The puts function writes characters from the string to the standard output file until it
encounters a null character. The function does not write the null character, but it
does write a newline character.
Example
This example writes “Hello” to the standard output file:
#include <stdioh>
int status;
char *sp;
sp = "Hello";
status = puts(sp);
3- 146
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
qsort
qsort
The qsort function sorts an array of elements in ascending order using a specified
comparison routine.
#include <stdlibh>
void qsort(void *base, size_t nmemb, size_t size,
int (*compar)(const void *, const void *));
base
points to the first element in the array to sort.
nmemb
specifies the number of elements in the array.
size
specifies the size in bytes of the array elements.
compar(void *, void *)
points to a function that compares two elements of size size, returning an integer less
than, equal to, or greater than zero if its first argument is respectively less than,
equal to, or greater than its second.
Return Value
none.
Guardian TNS C Library Calls Reference Manual—128833
3 -147
raise
Reference to Library Calls
raise
The raise function causes the indicated signal to be raised in the current process.
#include <signalh>
int raise(int sig);
sig
is the signal to be raised.
Return Value
is zero if the call is successful. Otherwise, a nonzero value is returned.
Usage Guidelines
•
The ISO C Standard defined signals SIGABRT, SIGINT, and SIGTERM can only be
generated by an explicit call to the raise function. The signal handler SIG_IGN can
be registered for these signals.
The condition specified by each of these signals is:
3- 148
SIGABRT
abnormal termination, such as is initiated by the abort function
SIGINT
receipt of an interactive attention signal
SIGTERM
a termination request sent to the program termination request sent to
the program
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
rand
rand
The rand function generates a pseudo-random number.
#include <stdlibh>
int rand(void);
Return Value
is a pseudo-random value in the range 0 through 32767.
Usage Guidelines
•
You can call srand to reset the pseudo-random sequence generator to a new starting
point. See “srand” on page 3-171 for more information.
Example
This example generates a pseudo-random number and places it in x:
#include <stdlibh>
/* ... */
int x;
x = rand();
/* ... */
Guardian TNS C Library Calls Reference Manual—128833
3 -149
read (supplementary)
Reference to Library Calls
read (supplementary)
The read function reads a number of bytes from a file opened for alternate I/O, storing
the input data in a buffer.
#include <fcntlh>
short read(int file_des, char *buf, short nbytes);
file_des
is the descriptor denoting a file opened for alternate I/O.
buf
points to the buffer where read stores the input data.
nbytes
specifies the number of bytes to be read from the file.
Return Value
is the number of bytes read or zero if read encounters the end of the file.
Example
This example reads 10 bytes from the file $a.b.c and writes them to the array named buf:
#include <fcntlh>
int filedes;
short status;
char buf[20];
short nbytes;
filedes = open("$a.b.c", O_RDONLY|O_BINARY);
nbytes = 10;
/* ... */
status = read(filedes, buf, nbytes);
readupdate (supplementary)
The readupdate function reads disk files (except Edit files) for update operations or reads
the $RECEIVE file for interprocess communication. These two different uses of
readupdate are discussed under “Usage Guidelines.”
#include <fcntlh>
short readupdate(short file_des, char *buf, short read_bytes,
long write_bytes);
3- 150
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
readupdate (supplementary)
file_des
is the descriptor denoting a file opened for alternate I/O.
buf
points to the string where readupdate stores the input message.
read_bytes
specifies the number of bytes to read.
write_bytes
specifies the number of bytes to write.
Return Value
depends upon the file type of file_des. When file_des refers to a disk file, readupdate
returns one of the following:
•
•
•
A positive value, which represents the number of characters read
The value zero, which indicates that no data was read because the file-position
indicator was at the end of the file
A negative value, which indicates that an error occurred
When file_des refers to the $RECEIVE file, readupdate returns one of the following:
•
•
A positive value, which represents the number of bytes read
A negative value, which indicates that an error occurred
Usage Guidelines
•
Updating a Disk File
You can use readupdate to read information at the file-position indicator (set by a
previous call to lseek). The readupdate function does not move the file-position
indicator. Consequently, you can overwrite (update) the information just read.
•
Reading an Interprocess Message from the $RECEIVE File
When the readupdate function reads the $RECEIVE file, the message read is a
request from another process or from the system. The program that calls readupdate
must interpret the request and then respond using reply. For information on
interpreting the $RECEIVE message and sending a reply, refer to “reply
(supplementary)” on page 3-154.
•
•
When a read of the $RECEIVE file sets errno to six, the message is a Guardian
system message.
When reading $RECEIVE, set errno to zero before calling readupdate.
Guardian TNS C Library Calls Reference Manual—128833
3 -151
realloc
Reference to Library Calls
realloc
The realloc function changes the size of a block of memory that you have allocated
using malloc or calloc.
#include <stdlibh>
void *realloc(void *str_ptr, size_t size);
str_ptr
points to an array of characters.
size
specifies the new size in bytes of the block of memory.
Return Value
points to the reallocated block of memory if the operation is successful; otherwise,
realloc returns the pointer value NULL.
Usage Guidelines
•
•
In many cases, the pointer returned by realloc is the same as str_ptr. However, if you
are increasing the size of a block of memory, lack of space could cause the run-time
library to copy the block to a new area.
If you have compiled your program for the large-memory model, realloc will
automatically enlarge the extended data segment when necessary.
Example
This example allocates an extra 5 bytes of memory for ptr to accommodate an expanded
string:
#include <stdlibh>
#include <stringh>
ptr = (char *)malloc(6);
/* ... */
strcpy(ptr, "01234");
/* ... */
ptr = realloc(ptr, 11);
strcat(ptr, "56789");
/* ... */
3- 152
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
rename
remove
The remove function purges a disk file.
#include <stdioh>
int remove(const char *file_name);
file_name
points to a string containing a valid Guardian file name.
Return Value
is zero if the operation is successful; otherwise, remove returns a nonzero value (and
the file is not purged).
Usage Guidelines
•
If the specified file is open, remove returns a nonzero value and does not close or
purge the file.
rename
The rename function changes the name of a disk file.
#include <stdioh>
int rename(const char *current_name, const char *new_name);
current_name
points to a string containing a valid Guardian file name, specifying the current name
of the file.
new_name
points to a string containing a valid Guardian file name, specifying the new name for
the file.
Return Value
is zero if the operation is successful; otherwise, rename returns a nonzero value (and
the name of the file is not changed).
Usage Guidelines
•
If the specified file is open, rename returns a nonzero value and does not rename the
file.
Guardian TNS C Library Calls Reference Manual—128833
3 -153
reply (supplementary)
Reference to Library Calls
reply (supplementary)
The reply function writes the response to a request made through the readupdate
function. Requests and responses are messages that are read from the $RECEIVE files
of two communicating processes.
#include <fcntlh>
short reply(char *message, short write_count,
[short message_tag], [short error_return]);
message
points to the string containing the reply message.
write_count
specifies the number of bytes to write from *message. write_count must be in the
range 0 through 2048, inclusive.
message_tag
is the message tag of the particular message that requested this reply.
error_return
is a short specifying an error number to be returned to the requester associated with
this reply. The requester receives error_return as if it were a normal file-system
error. If you do not specify error_return, reply uses the value zero.
Return Value
is the number of bytes actually written if the operation is successful. This return
value corresponds to the count-written parameter of the REPLY system procedure. If
an error occurs, reply returns the value -1.
Usage Guidelines
•
If you omit message_tag, but not error_return, you must retain the comma following
message_tag as a placeholder; for example:
count_written = reply(fd, buf, count, , error);
•
3- 154
If you opened $RECEIVE with a receive depth greater than one, you must specify
message_tag if you want to reply to a message other than the one most recently
received.
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
repmem (supplementary)
repmem (supplementary)
The repmem function replicates values through memory; that is, it copies a small block
of values (a template) repeatedly into a larger block of memory.
#include <memoryh>
void repmem(char *dest_blk, char *template,
size_t tmpl_size, size_t rep_count);
dest_blk
points to the block of memory to fill.
template
points to the template to replicate through *dest_blk.
tmpl_size
specifies the size in bytes of the template.
rep_count
specifies the number of times to replicate *template into *dest_blk.
Return Value
none.
Usage Guidelines
•
Note that the pointers used by repmem have type pointer to char. To use other types
of pointers, first convert them to pointers to char using the cast operator.
Example
This example replicates 10 templates of 10 bytes each:
#include <memoryh>
char dest[100];
char temp[10];
/* ... */
repmem(dest, temp, sizeof temp, 10);
Guardian TNS C Library Calls Reference Manual—128833
3 -155
rewind
Reference to Library Calls
rewind
The rewind function resets the file-position indicator to the beginning of a C file opened
for binary ANSI I/O.
#include <stdioh>
void rewind(FILE *stream);
stream
denotes a C file opened for binary ANSI I/O.
Return Value
none.
Usage Guidelines
•
The rewind function might be implemented as a macro in a future release.
Example
This example resets the file-position indicator for the file $a.b.c to the beginning of the
file:
#include <stdioh>
FILE *fp;
fp = fopen("$a.b.c", "rb+");
/* ... */
rewind(fp);
3- 156
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
scanf
scanf
The scanf function reads formatted data from the standard input file, uses the format
string to determine whether the data matches expectations and to determine the
necessary conversions, and writes converted data to one or more supplied variables.
#include <stdioh>
int scanf(const char *format, [obj_ptr...]);
format
points to a string that specifies how to convert the input text for assignment, using
subsequent arguments as pointers to the variables that receive the converted input.
Refer to “fscanf” on page 3-61 for a description of format.
obj_ptr...
is a list of pointers to variables, specifying where the results of the conversions
defined in *format are to be stored.
Return Value
is the number of items for which scanf found valid data, including all singlecharacter items in *format that were matched. If an error occurs, scanf returns the
value EOF.
Usage Guidelines
•
•
The conversion specifiers must agree in number and type with the pointers in
obj_ptr....
If you use the suppression feature (*), do not supply a pointer for that specifier.
Example
This example reads a number from the standard input file, converts it to a long floatingpoint number, and places it in variable x:
#include <stdioh>
double r;
double x;
scanf("%f", &x);
r = sqrt(x);
printf ("The square root of %f is %f", x, r);
Guardian TNS C Library Calls Reference Manual—128833
3 -157
setbuf
Reference to Library Calls
setbuf
The setbuf function attaches a user-supplied buffer to a file opened for ANSI I/O. This
buffer is then used for all I/O buffering, thus freeing the system resources normally used
for this purpose.
#include <stdioh>
void setbuf(FILE *stream, char *buffer);
stream
denotes a file opened for ANSI I/O.
buffer
points to the new file buffer. *buffer must accommodate at least BUFSIZ elements.
Return Value
none.
Usage Guidelines
•
•
•
You must call this function before any I/O is performed.
If buffer is NULL, this function has the same effect as setnbuf.
BUFSIZ is a predefined object-like macro that specifies the size in bytes of the
buffers used for streams. It is defined in the <stdioh> header.
Example
In this example, the setbuf function attaches the buffer named buf to $a.b.c:
#include <stdioh>
FILE *fp;
char buf[BUFSIZ];
fp = fopen("a.b.c ", "r+");
/* ... */
setbuf(fp, buf);
3- 158
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
setjmp
setjmp
The setjmp macro saves its calling environment in its argument for later use by the
longjmp function.
#include <setjmph>
int setjmp(jmp_buf env);
env
is a buffer of type jmp_buf, where setjmp saves its calling environment.
Return Value
is zero from the direct invocation of setjmp. If the return results from a subsequent
call to longjmp, the return value is determined by the val parameter in the longjmp
call.
Usage Guidelines
•
•
You must declare an environment buffer (of type jmp_buf) to pass as the env
parameter.
The type jmp_buf is declared in the header <setjmph>.
Example
The following example declares ebuf and passes its address to the setjmp function:
jmp_buf ebuf;
/* Declares a multi-word buffer */
/* ... */
switch (setjmp(ebuf))
{
case 0 : /* the original setjmp call, simply break */
break;
case 1 : /* longjmp call with val == 1
*/
/* ... */
break;
case 2 : /* longjmp call with val == 2
*/
/* ... */
break;
/* ... */
}
Guardian TNS C Library Calls Reference Manual—128833
3 -159
setlocale
Reference to Library Calls
setlocale
The setlocale function sets the specified category to the named locale. The setlocale
function can be used to change or query the program’s entire current locale or only
portions of the current locale.
#include <localeh>
char *setlocale(int category, const char *locale);
category
specifies the behavior to be changed. The various categories that can be changed are
defined in the locale category macro in the header localeh and described here in the
Usage Guidelines.
locale
names the locale whose conventions are to be used for the behavior designated by
category. The locale can be NULL, the empty string “”, or a case insensitive quoted
string. For this release, any quoted strings are accepted.
Return Value
For this release, the return value is always “C”, if the category and locale arguments
are valid. The return value of “C” specifies the standard C locale.
Usage Guidelines
•
If locale is NULL, the function does not change the locale but instead returns a
pointer to a string that is the name of the current locale for the indicated category.
This name is such that if the setlocale function is later called using the same value
for category and the returned string as the value for locale, then the effect is to
change the behavior to the one that was in effect when setlocale was called with the
NULL locale.
If locale is not NULL, setlocale changes the current locale and returns a string that
names the new locale.
For this release of the C compiler, the standard C locale is the only locale. The
setlocale function returns “C” if the arguments category and locale are valid.
3- 160
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
•
setmem (supplementary)
Most of the locale categories specify a portion of the locale to change or query. The
sole exception is the LC_ALL category that specifies the entire locale. The locale
categories are as follows:
Name
Behavior Affected
LC_ALL
All behavior
LC_COLLATE
Sorting information
LC_CTYPE
Character classification
information
LC_MONETARY
Currency printing information
LC_NUMERIC
Numeric printing information
LC_TIME
Date and time printing information
setmem (supplementary)
The setmem function initializes a block of memory to a specified character value.
#include <memoryh>
void setmem(char *mem_blk, size_t block_size, int value);
mem_blk
points to the block to initialize.
block_size
specifies the size in bytes of the block.
value
specifies the initialization value.
Return Value
none.
Example
This example initializes 20 bytes of memory to the character value a:
#include <memoryh>
char base[20];
unsigned nbytes;
char value;
nbytes = 20;
value = 'a';
setmem(base, nbytes, value);
Guardian TNS C Library Calls Reference Manual—128833
3 -161
setnbuf (supplementary)
Reference to Library Calls
setnbuf (supplementary)
The setnbuf function disables buffering for a file opened for ANSI I/O. For an equivalent
ANSI-standard function, refer to “setbuf” on page 3-158.
#include <stdioh>
void setnbuf(FILE *stream);
stream
denotes a file opened for ANSI I/O.
Return Value
none.
Usage Guidelines
•
Once you call setnbuf, which disables buffering, all input and output operations on
the specified file generate immediate I/O requests.
Example
In this example, the setnbuf function disables buffering for the file $a.b.c:
#include <stdioh>
FILE *fp;
fp = fopen("$a.b.c ", "r+");
/* ... */
setnbuf(fp);
setvbuf
The setvbuf function attaches a user-supplied buffer or disables buffering to a file
opened for ANSI I/O.
#include <stdioh>
int setvbuf(FILE *stream, char *buf, int mode, size_t size);
stream
denotes a file opened for ANSI I/O.
3- 162
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
setvbuf
buf
points to the new file buffer. The buffer that buf points to must accommodate at least
BUFSIZ elements.
mode
indicates how stream will be buffered as follows:
_IOFBF
_IOLBF
_IONBF
I/O to be full buffered
I/O to be line buffered
I/O to be unbuffered
The macros _IOFBF, _IOLBF, _IONBF are defined in the header stdioh. Full
buffering (_IOFBF) is equivalent to line buffering (_IOLBF) as both will perform
full buffering for a file opened for ANSI I/O. Unbuffering (_IONBF) disables
buffering for a file opened for ANSI I/O.
size
specifies the size of the buffer that buf points to.
Return Value
is zero if the call is successful. Otherwise, the function returns a nonzero value
under the following conditions: if an invalid value is given for mode, if a null pointer
is given for stream, if a value less then BUFSIZ is given for size, or if there is lack of
memory space for the requested buffer.
Usage Guidelines
•
•
•
•
The setvbuf function can be used only after the stream pointed to by stream has been
associated with an open file and before any other operation is performed on the
stream.
If buf is null, the C run-time library allocates a buffer with the size of BUFSIZ. If
buf is not null, the function attaches the buffer pointed to be buf as a user-supplied
buffer to a file opened for ANSI I/O. BUFSIZ is used as the size of the buffer for all
circumstances.
BUFSIZ is a predefined object-like macro that specifies the size in bytes of the
buffers C uses for streams. It is defined in the header stdioh.
Once a user calls setvbuf with mode of _IONBF, which disables buffering, all input
and output operations on the specified file generate immediate I/O requests.
Guardian TNS C Library Calls Reference Manual—128833
3 -163
signal
Reference to Library Calls
Example
#include <stdioh>
FILE *fp;
char buf[BUFSIZ];
int ret_value;
fp = fopen("$x.y.file1", "r+");
ret_value = setvbuf(fp, buf, _IOLBF, BUFSIZ);
signal
The signal function associates signal handlers with specific signals.
#include <signalh>
void (*signal(int sig, void (*func) (int)))(int);
sig
is a specific signal. The signals are defined as symbolic constants in the header
signalh such that an integer value is associated with each signal. The possible signals
are described in the Usage Guidelines.
func
is a pointer to the signal handler.
Return Value
If successful, the signal function returns the pointer value func for the most recent
call to the signal function where the same first argument sig was specified.
Otherwise, the value of SIG_ERR is returned.
3- 164
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
signal
Usage Guidelines
•
An exceptional condition, or signal, is generated by an abnormal event. For example,
a floating point exception occurs when two very large floating point numbers are
multiplied together.
The exceptional conditions that can be handled by the operating system are defined
as symbolic constants in the header signalh. Some examples are:
SIGFPE
Arithmetic overflow
SIGILL
Illegal instruction
SIGSEGV
Illegal address reference
If an exceptional condition is raised in a process, then the typical default action of
the operating system is to terminate the process. You can use the signal function to
invoke a signal handler that replaces the default system action.
The signal function takes two arguments, an int and a pointer to a function that takes
an int and returns nothing. The signal function returns a pointer to a function that
takes an int and returns nothing.
The function call signal(sig, func) associates the signal sig with the signal handler
func(). This causes the system to pass sig as an argument to func() and invoke func()
when the signal sig is raised.
•
The standard C signal handlers are SIG_DFL, SIG_IGN, and SIG_ERR.
The signal handler SIG_DFL is initially registered by the C run-time library to all
signals, that is the equivalent of signal(xxx, SIG_DFL) is performed for each signal.
The action of SIG_DFL is equivalent to closing all files and aborting the program
with a stack dump.
A call to signal of the form signal(sig, SIG_IGN) means that the signal sig is to be
ignored. The Tandem C implementation of signal handling does not allow certain
signals to be ignored or returned from. If a signal is described as not allowing
SIG_IGN to be registered for it then if a user supplied handler executes the return
statement the program will be aborted as if SIG_DFL was used for that signal. If the
user attempts to return control to his program from his signal handler by way of the
longjmp function then he is responsible for insuring the program’s environment is
stable.
•
The standard C signal handlers SIG_DFL, SIG_IGN, and SIG_ERR are defined in
the header signalh to appear like functions. However, they should never be used
explicitly as the results are undefined. They should be used as in the following
example:
signal(SIGTIMEOUT, SIG_IGN);
Guardian TNS C Library Calls Reference Manual—128833
/* ignore the signal
SIGTIMEOUT
*/
3 -165
signal
Reference to Library Calls
•
•
The ANSI defined signals SIGFPE, SIGILL, and SIGSEGV correspond to the
following operating system traps:
SIGFPE
Arithmetic overflow
SIGILL
Illegal instruction
SIGSEGV
Illegal address reference
The Tandem defined signals that follow are Tandem C specific signals and directly
correspond to a particular operating system trap.
•
SIGSTK
The SIGSTK signal is equivalent to the STACK OVERFLOW trap. This signal
can never be returned from because the signal handler is placed at a fixed point
on the stack and if the stack has overflowed then the handler is sure to have
overwritten what was on the stack. A stack dump that is done by the SIG_DFL
handler might not be correct because the information on the stack might have
been overwritten.
•
SIGTIMEOUT
This signal corresponds to the operating system trap PROCESS LOOP-TIMER
TIMEOUT.
•
SIGMEMMGR
The SIGMEMMGR signal corresponds to the operating system trap MEMORY
MANAGER DISK READ ERROR.
•
SIGNOMEM
The SIGNOMEM signal corresponds to the operating system trap NO
MEMORY AVAILABLE.
•
SIGMEMERR
The SIGMEMERR signal corresponds to the operating system trap
UNCORRECTABLE MEMORY ERROR.
•
SIGLIMIT
The SIGLIMIT signal is a special signal. This signal occurs when the limit of
the operating system is exceeded.
For more information on these Tandem defined signals, refer to the Guardian
Procedure Calls Reference Manual and the Guardian Programmer’s Guide.
3- 166
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
•
sin
The ANSI defined signals SIGABRT, SIGINT, and SIGTERM can only be
generated by an explicit call to the raise function.
The condition specified by each of these signals is:
SIGABRT
abnormal termination, such as is initiated by the abort function
SIGINT
receipt of an interactive attention signal
SIGTERM
a termination request sent to the program
sin
The sin function computes the sine of its argument.
#include <mathh>
double sin(double expr);
expr
specifies an angle in radians.
Return Value
is the sine of expr.
Example
This example prints “The sine is 1.000000.”:
#include <mathh>
#include <stdioh>
int main(void)
{
double x, r;
x = 1.5708;
r = sin(x);
printf("The sine is %f.", r);
}
Guardian TNS C Library Calls Reference Manual—128833
3 -167
sinh
Reference to Library Calls
sinh
The sinh function computes the hyperbolic sine of its argument.
#include <mathh>
double sinh(double expr);
expr
is an expression of type double.
Return Value
is the hyperbolic sine of expr. sinh returns HUGE_VAL if a positive overflow
occurs, -HUGE_VAL if a negative overflow occurs, or zero if an underflow occurs.
In all three of these cases, sinh also sets errno to ERANGE (a range error).
Example
This example prints “The hyperbolic sine is 2.301308.”:
#include <mathh>
#include <stdioh>
int main(void)
{
double x, r;
x = 1.5708;
r = sinh(x);
printf("The hyperbolic sine is %f.", r);
}
3- 168
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
sprintf
sprintf
The sprintf function writes formatted data to a string.
#include <stdioh>
int sprintf(char *str_ptr, const char *format, [expr...]);
str_ptr
points to the string where sprintf stores the formatted data.
format
points to a string that contains characters and conversion specifiers. Refer to
“fprintf” on page 3-51 for a description of format and conversion specifiers.
expr...
is the list of arguments to be formatted using the conversion specifiers in *format.
Return Value
is the number of characters output (not counting the null character) if the operation
is successful; otherwise, sprintf returns a negative value.
Usage Guidelines
•
To print a percent sign, you must precede it with a percent sign; for example:
sprintf(sp, "Stock went up %d%%\n", increase);
•
•
The sprintf function appends a null character to the output string.
When the converted sprintf argument has fewer characters than the specified field
width, sprintf uses blanks to pad out the extra space. To request padding with zeroes
instead of blanks, precede the field width with a zero.
Example
In this example, the sprintf function fetches an argument, formats it as a character string,
and stores it in an array of char:
#include <stdioh>
char sp[50];
char *x;
/* ... */
x = "Carolyn";
sprintf(sp, "Hello, %s", x);
Guardian TNS C Library Calls Reference Manual—128833
3 -169
sqrt
Reference to Library Calls
sqrt
The sqrt function computes the square root of its argument.
#include <mathh>
double sqrt(double expr);
expr
is an expression of type double with a positive value.
Return Value
is the square root of expr. If expr is negative, sqrt returns zero and sets errno to
EDOM (a domain error).
Example
This example prints “The square root of 25.000000 is 5.000000.”:
#include <stdioh>
#include <mathh>
int main(void)
{
double r;
double x;
x=25.0;
r = sqrt(x);
printf ("The square root of %f is %f.", x, r);
}
3- 170
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
srand
srand
The srand function resets the pseudo-random sequence generator to a new starting point.
#include <stdlibh>
void srand(unsigned int seed);
seed
specifies the new starting point, or seed, for the pseudo-random sequence generator.
Return Value
none.
Usage Guidelines
•
•
At program startup, the generator’s seed is set to one.
Calling srand with a given value of seed always produces the same sequence of
pseudo-random numbers.
Example
This example resets the pseudo-random sequence generator to a new starting point:
#include <stdlibh>
/* ... */
int x;
unsigned seed;
seed = 15;
srand(seed);
/* ... */
x = rand();
Guardian TNS C Library Calls Reference Manual—128833
3 -171
sscanf
Reference to Library Calls
sscanf
The sscanf function reads formatted data from a character string, uses the format string
to determine whether the data matches expectations and to determine the necessary
conversions, and writes converted data to one or more supplied variables.
#include <stdioh>
int sscanf(const char *str_ptr, const char *format,
[obj_ptr...]);
str_ptr
points to the data to scan and convert.
format
points to a string that specifies how to convert the input text for assignment, using
subsequent arguments as pointers to the variables that receive the converted input.
Refer to “fscanf” on page 3-61 for a description of format.
obj_ptr...
is a list of pointers to variables, specifying where the results of the conversions
defined in *format are to be stored.
Return Value
is the number of items for which sscanf found valid data, including all singlecharacter items in *format that were matched. If an error occurs, sscanf returns the
value EOF.
Usage Guidelines
•
•
•
3- 172
The conversion specifiers must agree in number and type with the pointers in
obj_ptr....
If you use the suppression feature (*), do not supply a pointer for that specifier.
In C-series releases, sscanf returns a -1 if no conversion takes place. In D-series
releases, sscanf returns a 0 if no conversion takes place.
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
sscanf
Example
This example reads input from a string, converts it to a long float (double) value, and
stores it in a variable of type double:
#include <stdioh>
int status;
double r, x;
char sp[25];
/* ... */
status = sscanf(sp, "%f", &x);
r = sqrt(x);
printf ("The square root of %f is %f", x, r);
Guardian TNS C Library Calls Reference Manual—128833
3 -173
stcarg (supplementary)
Reference to Library Calls
stcarg (supplementary)
The stcarg function scans a string until it finds one of the characters from another
specified string.
#include <stringh>
size_t stcarg(char *str1_ptr, char *str2_ptr);
str1_ptr
points to the string to scan.
str2_ptr
points to the string to scan for.
Return Value
is the number of characters scanned in *str1_ptr, or the length of *str1_ptr if none
of the characters are found.
Usage Guidelines
•
•
The stcarg function scans a string until it finds one of the characters in the other
string, or until it encounters a null character.
While scanning the string, stcarg ignores text that is inside single or double
quotation marks, or text that follows an unmatched single or double quotation mark.
It also ignores any characters that are preceded by a backslash character.
Example
This example prints “token_number_1”, which is the string of characters that precedes
the first break character:
#include <stringh>
#include <stdioh>
int main(void)
{
int indx;
int length;
char *text;
char *break_chars;
/*
/*
/*
/*
loop control index
length of current token
pointer to text to be processed
chars which end an argument
*/
*/
*/
*/
break_chars=";: !."; /* chars which end an argument */
text = "token_number_1 12345;abc";
length = stcarg(text, break_chars);
for(indx=0; indx<length; indx++)
printf("%c", text[indx]);
printf("\n");
}
3- 174
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
stccpy (supplementary)
stccpy (supplementary)
The stccpy function copies not more than a specified number of characters from one
string to another. For a similar ISO C Standard function, see“strncpy” on page 3-205.
#include <stringh>
size_t stccpy(char *str1_ptr, char *str2_ptr, size_t max);
str1_ptr
points to the location to copy to.
str2_ptr
points to the string to copy.
max
specifies the maximum number of characters to copy. max must be a positive integer.
Return Value
is the number of characters actually copied from *str2_ptr to *str1_ptr.
Usage Guidelines
•
The string at str1_ptr is terminated by a null character, whether the maximum count
or a null character stopped the copy operation.
Guardian TNS C Library Calls Reference Manual—128833
3 -175
stcd_i (supplementary)
Reference to Library Calls
stcd_i (supplementary)
The stcd_i function converts a string of decimal characters to an integer.
#include <stdlibh>
int stcd_i(char *str_ptr, int *int_ptr);
str_ptr
points to the string to convert.
int_ptr
points to the variable of type int where stcd_i stores the converted value.
Return Value
is the number of characters scanned.
Usage Guidelines
•
•
•
The string to convert can contain an optional sign and then a string of digits.
The stcd_i function does not skip leading space characters.
The stcd_i function halts scanning when it encounters a non-decimal character.
Example
This example converts the string “234” to an integer:
#include <stdlibh>
#include <stdioh>
int main(void)
{
int result;
char *string;
int count;
string = "234";
count = stcd_i(string, &result);
printf("%d\n", result); /* prints "234" */
}
3- 176
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
stcd_l (supplementary)
stcd_l (supplementary)
The stcd_l function converts a string of decimal characters to a long integer.
#include <stdlibh>
int stcd_l(char *str_ptr, long *int_ptr);
str_ptr
points to the string to convert.
int_ptr
points to the variable of type long where stcd_l stores the converted value.
Return Value
is the number of characters scanned.
Usage Guidelines
•
•
•
The string to convert can contain an optional sign and then a string of digits.
The stcd_l function does not skip leading space characters.
The stcd_l function halts scanning when it encounters a non-decimal character.
Example
This example converts the string “1234567” to a long integer:
#include <stdlibh>
#include <stdioh>
int main(void)
{
char *string;
long result;
int count;
string = "1234567";
count = stcd_l(string, &result);
printf("%ld\n", result); /* prints "1234567" */
}
Guardian TNS C Library Calls Reference Manual—128833
3 -177
stch_i (supplementary)
Reference to Library Calls
stch_i (supplementary)
The stch_i function converts a string of hexadecimal characters to an integer.
#include <stdlibh>
int stch_i(char *str_ptr, int *int_ptr);
str_ptr
points to the string to convert.
int_ptr
points to the variable of type int where stch_i stores the converted value.
Return Value
is the number of characters scanned, or zero if *str_ptr does not begin with a valid
hexadecimal digit.
Usage Guidelines
•
•
The stch_i function does not skip leading space characters.
This function halts the conversion of the string when it encounters a character that is
not a valid hexadecimal digit.
Example
This example converts the hexadecimal string “1a2” to an integer:
#include <stdlibh>
#include <stdioh>
int main(void)
{
int num;
int count;
char *string;
string = "1a2";
/* hexadecimal for 418 */
count = stch_i(string,&num);
printf("%d",num); /* prints "418" */
}
3- 178
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
stci_d (supplementary)
stci_d (supplementary)
The stci_d function converts a signed integer to a string of decimal characters.
#include <stdlibh>
int stci_d(char *str_ptr, int integer, int outlen);
str_ptr
points to the string where stci_d stores the converted decimal value.
integer
is the integer to convert.
outlen
is the size of the array pointed to by str_ptr.
Return Value
is the length of the resulting string, excluding the terminating null character.
Usage Guidelines
•
•
•
The stci_d function does not copy leading zeros to the output string. The output
string is terminated with a null character.
If the integer is negative, the output string is preceded by a negative sign.
If the integer is zero, a single zero character is produced.
Example
This example converts the integer 2001 to a string of decimal characters:
#include <stdlibh>
#include <stdioh>
int main(void)
{
int num;
size_t length;
char string[10];
num = 2001;
length = stci_d(string,num,10);
printf("%s",string);
/* convert to */
/* string form */
/* prints "2001" */
}
Guardian TNS C Library Calls Reference Manual—128833
3 -179
stcis (supplementary)
Reference to Library Calls
stcis (supplementary)
The stcis function scans one string until it finds a character not specified in another
string. For an equivalent ISO C Standard function, refer to “strspn” on page 3-208.
#include <stringh>
size-t stcis(char *str1_ptr, char *str2_ptr);
str1_ptr
points to the string to scan.
str2_ptr
points to the string to scan for. This string can contain any legal character.
Return Value
is the number of characters scanned, except for the character that ended the scan. If
the first character of *str1_ptr is not in *str2_ptr, then stcis returns zero.
Example
This example scans string s and finds seven characters before it encounters a character
that is not also in string i:
#include <stringh>
#include <stdioh>
int main(void)
{
size_t length;
char *s;
char *i;
s = "+147692 231 37356841";
i = "1234567890-+"; /* list of included characters */
length = stcis(s,i);
printf("%d\n",length); /* prints "7" */
}
3- 180
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
stcisn (supplementary)
stcisn (supplementary)
The stcisn function scans one string until it finds a character that is specified in another
string. For an equivalent ISO C Standard function, refer to “strcspn” on page 3-197.
#include <stringh>
size-t stcisn(char *str1_ptr, char *str2_ptr);
str1_ptr
points to the string to scan.
str2_ptr
points to the string to scan for. This string can contain any legal character.
Return Value
is the number of characters scanned, except for the character that ended the scan. If
the first character in *str1_ptr is also in *str2_ptr, then stcisn returns zero.
Example
This example scans string s and finds 11 characters before it encounters a character that
is also in string b:
#include <stringh>
#include <stdioh>
int main(void)
{
size_t length;
char *s;
char *b;
s = "Tandem (adv.): one behind another.";
b = ":!;.";
/* list of break characters */
length = stcisn(s, b);
printf("%d\n",length);
/* prints "11" */
}
Guardian TNS C Library Calls Reference Manual—128833
3 -181
stclen (supplementary)
Reference to Library Calls
stclen (supplementary)
The stclen function computes the length of a string. See “strlen” on page 3-201 for an
equivalent ISO C Standard function.
#include <stringh>
size_t stclen(char *str_ptr);
str_ptr
points to the string to measure.
Return Value
is the number of characters in *str_ptr, except for the terminating null character.
stcpm (supplementary)
The stcpm function scans a string to find the first occurrence of a substring that matches
a specified pattern.
#include <stringh>
int stcpm(char *str_ptr, char *pat_ptr, char **match_ptr);
str_ptr
points to the string to scan.
pat_ptr
points to the pattern string. The pattern is specified with regular expression
notations:
?
matches any single character
chr*
matches zero or more occurrences of chr
chr+ matches one or more occurrences of chr
chr
matches chr
match_ptr
points to the matched string (if found).
Return Value
is the length of the matching substring, if found; otherwise, stcpm returns the value 1 and sets *match_ptr to the pointer value NULL.
3- 182
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
stcpm (supplementary)
Usage Guidelines
•
•
Note that match_ptr has type pointer to pointer to char. This function returns the
length of the first matching substring; a pointer to it is returned through match_ptr.
You can use the backslash (\) as an escape character to match one of the special
characters. If you specify pat_ptr as a string literal, you must use two backslashes.
For example, to search for the string “??” you would specify the string literal:
"\\?\\?"
Similarly, to search for a single backslash (by specifying “\\” as the pattern string)
you would specify the string literal:
"\\\\"
Example
This example scans a string to find the first occurrence of the pattern “FO?T”:
#include <stringh>
int main(void)
{
int length;
char *string;
char *pattern;
char *match;
string = "TANDEM is a FORTUNE 500 company";
pattern = "FO?T"; /* will match "FO", then */
/* any char, then "T"
*/
length = stcpm(string, pattern, &match);
printf("%d %s\n", length, match);
/* prints "4 FORTUNE 500 company" */
}
Guardian TNS C Library Calls Reference Manual—128833
3 -183
stcpma (supplementary)
Reference to Library Calls
stcpma (supplementary)
The stcpma function scans a string to determine whether it starts with a substring that
matches a specified pattern.
#include <stringh>
int stcpma(char *str_ptr, char *pat_ptr);
str_ptr
points to the string to scan.
pat_ptr
points to the pattern string. The pattern is specified with regular expression
notations:
?
matches any single character
chr*
matches zero or more occurrences of chr
chr+ matches one or more occurrences of chr
chr
matches chr
Return Value
is the length of the matching substring, if found; otherwise, stcpma returns the
value -1.
Usage Guidelines
•
3- 184
You can use the backslash (\) as an escape character to match one of the special
characters. For more information, refer to “stcpm (supplementary)” on page 3-182.
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
stcpma (supplementary)
Example
This example scans a string for the pattern “st?rs s???e”:
#include <stringh>
#include <stdioh>
int main(void)
{
int indx;
size_t length;
char *string, *pattern;
string = "stars shine on alabama";
pattern = "st?rs s???e";
length = stcpma(string, pattern);
for(indx=0; indx<length; indx++)
printf("%c",string[indx]);
printf("\n");
}
Guardian TNS C Library Calls Reference Manual—128833
3 -185
stcu_d (supplementary)
Reference to Library Calls
stcu_d (supplementary)
The stcu_d function converts an unsigned integer to a string of decimal characters.
#include <stdlibh>
int stcu_d(char *str_ptr, unsigned value, int str_size);
str_ptr
points to the string where stcu_d stores the converted decimal value.
value
is the integer to convert.
str_size
specifies the number of bytes in *str_ptr.
Return Value
is the length of the resulting string, except for the terminating null character.
Usage Guidelines
•
•
The stcu_d function appends a null character to the resulting string.
If value is zero, the converted string contains a single zero character.
Example
This example converts the unsigned integer 65432 to a string:
#include <stdlibh>
#include <stdioh>
int main(void)
{
unsigned num;
size_t length;
char string[10];
num = 65432;
length = stcu_d(string, num, 10);
/* convert to string form */
printf("%s", string); /* prints "65432" */
}
3- 186
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
stpblk (supplementary)
stpblk (supplementary)
The stpblk function scans a string for a nonspace character.
#include <stringh>
char *stpblk(char *str_ptr);
str_ptr
points the string to scan.
Return Value
points to the first nonspace character in *str_ptr.
Usage Guidelines
•
A nonspace character is any character for which the isspace returns zero.
Example
This example prints “Paula”:
#include <stringh>
#include <stdioh>
int main(void)
{
char *q;
char *s;
s = "
\nPaula";
q = stpblk(s);
printf("%s",q);
/* skip blanks */
}
Guardian TNS C Library Calls Reference Manual—128833
3 -187
stpbrk (supplementary)
Reference to Library Calls
stpbrk (supplementary)
The stpbrk function scans a string for a character that is in a given list of characters. See
“strpbrk” on page 3-206 for an equivalent ISO C Standard function.
#include <stringh>
char *stpbrk(char *scan_str, char *chr_list);
scan_str
points to the string to scan.
chr_list
points to the string containing the characters to scan for.
Return Value
points to the first occurrence in *scan_str of one of the characters in *chr_list. If
*scan_str does not contain any of the characters in *chr_list, then stpbrk returns the
pointer value NULL.
stpchr (supplementary)
The stpchr function scans a string for the first occurrence of a given character. See
“strchr” on page 3-193 for an equivalent ISO C Standard function.
#include <stringh>
char *stpchr(char *scan_str, int chr);
scan_str
points to the string to scan.
chr
specifies the character to scan for.
Return Value
points to the first occurrence in *scan_str of chr. If *scan_str does not contain chr,
then stpchr returns the pointer value NULL.
3- 188
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
stpsym (supplementary)
stpsym (supplementary)
The stpsym function gets a symbol from a string and stores it in another specified string.
#include <stringh>
char *stpsym(char *str_ptr, char *dest_ptr, int dest_size);
str_ptr
points to the string to scan.
dest_ptr
points to the string where stpsym stores the symbol.
dest_size
specifies the size in bytes of *dest_ptr.
Return Value
points to the next character in the string after the symbol. If stpsym does not find a
symbol, it returns the pointer str_ptr.
Usage Guidelines
•
•
•
A symbol consists of an alphabetic character followed by zero or more alphanumeric
characters.
The stpsym function does not skip leading space characters.
Note that if you want to retrieve a symbol of length n, you need to ensure that
*dest_ptr can accommodate at least n+1 elements, and that you pass n+1 as
dest_size. This extra element allows for the terminating null character.
Guardian TNS C Library Calls Reference Manual—128833
3 -189
stpsym (supplementary)
Reference to Library Calls
Example
This example scans the string text until it encounters a non-alphanumeric character; it
then writes the string to symbol:
#include <stringh>
#include <stdioh>
int main(void)
{
char *text;
char symbol[10];
char *r;
text = "alpha1 2";
r = stpsym(text,symbol,10);
printf("%s",symbol);
/* prints "alpha1" */
}
3- 190
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
stptok (supplementary)
stptok (supplementary)
The stptok function scans a source string for a token and copies the token to another
string. The token consists of all characters in the source string up to, but not including,
the first delimiter.
#include <stringh>
char *stptok(char *sstr_ptr, char *tstr_ptr, int tmax,
char *bstr_ptr);
sstr_ptr
points to the string to scan.
tstr_ptr
points to the string where stptok copies the token.
tmax
is the maximum token length, presumably the size of the string *tstr_ptr. Tokens
greater than this length are truncated.
bstr_ptr
points to a string consisting of token delimiter characters; these characters cannot be
part of a token.
Return Value
points to the next character in the source string (the token delimiter that stopped the
scan).
Usage Guidelines
•
•
•
The stptok function writes a null character to *tstr_ptr immediately following the
token.
Space characters at the beginning of *sstr_ptr are not skipped.
This function is nonstandard; see “strtok” on page 3-211 for a similar standard
function.
Guardian TNS C Library Calls Reference Manual—128833
3 -191
strcat
Reference to Library Calls
strcat
The strcat function concatenates two strings.
#include <stringh>
char *strcat(char *str1_ptr, const char *str2_ptr);
str1_ptr
points to the string to which the second string is concatenated.
str2_ptr
points to the string that is concatenated to the first string.
Return Value
points to the resulting string.
Usage Guidelines
•
•
The strcat function assumes that *str1_ptr can accommodate both *str1_ptr and
*str2_ptr.
The strcat function appends a null character to the result.
Example
This example concatenates s2 to the end of s1 and prints “Hi Paula!”:
#include <stringh>
#include <stdioh>
int main(void)
{
char s1[20];
char *s2;
s1[0]
s1[1]
s1[2]
s1[3]
=
=
=
=
'H';
'i';
' ';
'\0'; /* NULL */
s2 = "Paula!\n";
strcat(s1,s2);
printf("%s",s1);
}
3- 192
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
strchr
strchr
The strchr function scans a string for the first occurrence of a given character.
#include <stringh>
char *strchr(const char *str_ptr, int chr);
str_ptr
points to the string to scan.
chr
is the character to scan for.
Return Value
points to the first occurrence in *str_ptr of chr. If *str_ptr does not contain chr, then
strchr returns the pointer value NULL.
Example
This example searches string s for the character “a” and prints the character:
#include <stringh>
#include <stdioh>
int main(void)
{
char *p;
char *s;
int c;
c = 'a';
s = "This is an example";
p = strchr(s, c);
printf("%c", *p);
}
Guardian TNS C Library Calls Reference Manual—128833
3 -193
strcmp
Reference to Library Calls
strcmp
The strcmp function compares two strings alphabetically.
#include <stringh>
int strcmp(const char *str1_ptr, const char *str2_ptr);
str1_ptr
points to the first string.
str2_ptr
points to the second string.
Return Value
is zero if the two strings are equal, a negative value if *str1_ptr is less than
*str2_ptr, or a positive value if *str1_ptr is greater than *str2_ptr.
Usage Guidelines
•
If the two strings are different lengths but match to the end of the shorter string, the
shorter string is considered less than the longer string.
Example
This example compares two strings and prints “s1 is greater than s2”:
#include <stringh>
#include <stdioh>
int main(void)
{
int value;
char *s1;
char *s2;
s1 = "Opus is a penguin";
s2 = "Opus is a flightless water fowl";
value = strcmp(s1,s2);
/* prints "s1 is greater than s2" because */
/*
'p' is greater than 'f'
*/
if (value<0)
printf("s1 is less than s2\n");
else if (value>0)
printf("s1 is greater than s2\n");
else
printf("s1 equals s2\n");
}
3- 194
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
strcoll
strcoll
The strcoll function compares two strings according to the rules of the current locale
collating sequence. The strcoll function compares each byte, the same as the strcmp
function does, because there exists no defined collating sequence for a 2-byte character
set.
#include <stringh>
int strcoll(const char *s1, const char *s2);
s1
points to the first string.
s2
points to the second string.
Return Value
is zero if the two strings are equal, is a positive number if the string pointed to by s1
is greater than the string pointed to by s2, is a negative number if the string pointed
to by s1 is less than the string pointed to by s2.
Guardian TNS C Library Calls Reference Manual—128833
3 -195
strcpy
Reference to Library Calls
strcpy
The strcpy function copies one string to another.
#include <stringh>
char *strcpy(char *str1_ptr, const char *str2_ptr);
str1_ptr
points to the target string.
str2_ptr
points to the string to be copied.
Return Value
points to the target string; that is, the return value is str1_ptr.
Usage Guidelines
•
If the strings overlap, the strcpy function does not preserve data.
Example
This example copies string s2 to s1 and prints s1:
#include <stringh>
int main(void)
{
char s1[20];
char *s2;
char *s3;
s2 = "This is a string";
s3 = strcpy(s1,s2);
printf("%s",s3);
/* "This is a string" */
}
3- 196
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
strcspn
strcspn
The strcspn function scans a string until it finds a character that is found in another
specified string.
#include <stringh>
size_t strcspn(const char *str1_ptr, const char *str2_ptr);
str1_ptr
points to the string to scan.
str2_ptr
points to the string containing the characters to scan for.
Return Value
is the length of the initial segment of the *str1_ptr that consists entirely of
characters not listed in *str2_ptr.
Example
This example scans string s and finds 10 characters before it encounters a character that
is also in string i:
#include <stringh>
#include <stdioh>
int main(void)
{
size_t length;
char *s;
char *i;
s = "An example: how to use strcspn";
i = ",.;:";
length = strcspn(s,i);
printf("%d",length);
/* prints "10"
*/
}
Guardian TNS C Library Calls Reference Manual—128833
3 -197
strerror
Reference to Library Calls
strerror
The strerror function retrieves the textual error message corresponding to one of the
predefined values that errno can acquire.
#include <stringh>
char *strerror(int errval);
errval
is the error value whose corresponding textual message strerror retrieves. For a list
of the predefined error values, refer to “<errnoh>” on page 2-2.
Return Value
points to a string containing the textual error message corresponding to errval.
Usage Guidelines
•
3- 198
The strerror function returns a pointer to static data within the C run-time library.
Consequently, you should not modify the string that this pointer points to.
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
strftime
strftime
The strftime function writes characters into the array pointed to by s under the direction
of the format string pointed to by format. At most maxsize characters are written. If
more than maxsize characters are required, the function returns zero and the contents of s
is indeterminate; otherwise the length of s is returned, not counting the null terminator.
The format string consists of ordinary characters and conversion specifiers that
determine how values from the broken down time in the structure pointed to by timeptr
are to be written.
#include <timeh>
size_t strftime(char *s, size_t maxsize, const char *format,
const struct tm *timeptr);
s
points to the character array into which the strftime function writes the characters.
maxsize
specifies the maximum number of characters that the strftime function is allowed to
write into the array. This maximum number must include a terminating null
character.
format
points to a string that consists of zero or more conversion specifiers.
timeptr
points to the structure that contains the broken down time. This structure must be of
type struct tm.
Guardian TNS C Library Calls Reference Manual—128833
3 -199
strftime
Reference to Library Calls
Usage Guidelines
•
3- 200
The format string consists of zero or more conversion specifiers. A conversion
specifier consists of a % character followed by a character that determines the
behavior of the conversion specifier. Each conversion specifier is replaced by the
appropriate characters as described in the following list:
Conversion
Specifier
What gets printed
Example
%a
abbreviated weekday name
Mon
%A
full weekday name
Monday
%b
abbreviated month name
Sep
%B
full month name
September
%c
date and time
Sep 16
%d
day of the month
01
%H
hour of the 24-hour day (00-24)
22
%I
hour of the 12-hour day (00-12)
09
%j
day of the year
263
%m
month of the year
11
%M
minutes after the hour
21
%p
AM or PM
PM
%S
seconds after the minute
59
%U
week of the year (0-53)
34
%w
day of the week (0-6), Sunday = 0
5
%W
week of the year with first
Monday as first day of week 1
24
%x
date
01/20/1957
%X
time
3:45:08 PM
%y
year of the century
92
%Y
year
1992
%%
percent character
%
01:03:52 1773
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
strlen
strlen
The strlen function computes the length of a string.
#include <stringh>
size_t strlen(const char *str_ptr);
str_ptr
points to the string to measure.
Return Value
is the number of characters in *str_ptr, except for the terminating null character.
Example
This example measures string s and prints its length:
#include <stringh>
#include <stdioh>
int main(void)
{
char *s;
s = "Go Tandem";
printf("%d",strlen(s));
/* "9" */
}
Guardian TNS C Library Calls Reference Manual—128833
3 -201
strncat
Reference to Library Calls
strncat
The strncat function concatenates not more than a specified number of characters from
one string to another.
#include <stringh>
char *strncat(char *str1_ptr, const char *str2_ptr,
size_t max);
str1_ptr
points to the string to append to.
str2_ptr
points to the string that is concatenated to the first string.
max
specifies the maximum number of characters from *str2_ptr to append to *str1_ptr.
max must be a positive integer.
Return Value
points to the resulting string.
Example
This example prints “BEATLES: It was twenty years ago today!”:
#include <stringh>
#include <stdioh>
int main(void)
{
char str1[50], *str2, *str3;
str1[0]
str1[1]
str1[2]
str1[3]
str1[4]
str1[5]
str1[6]
str1[7]
str1[8]
str1[9]
=
=
=
=
=
=
=
=
=
=
'B';
'E';
'A';
'T';
'L';
'E';
'S';
':';
' ';
NULL;
str2 ="It was twenty years ago today! Yeah!";
str3 = strncat(str1,str2,31);
printf("%s\n",str3);
}
3- 202
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
strncmp
strncmp
The strncmp function compares two strings alphabetically for a given maximum number
of characters.
#include <stringh>
int strncmp(const char *str1_ptr, const char *str2_ptr,
size_t max);
str1_ptr
points to the first string to compare.
str2_ptr
points to the second string to compare.
max
specifies the maximum number of characters to compare. max must be a positive
integer.
Return Value
is zero if the two strings are equal, a negative value if *str1_ptr is less than
*str2_ptr, or a positive value if *str1_ptr is greater than *str2_ptr.
Usage Guidelines
•
If the first string has fewer max characters and matches the beginning of the second
string, the first string is considered less than the second string.
Guardian TNS C Library Calls Reference Manual—128833
3 -203
strncmp
Reference to Library Calls
Example
This example prints “s1 equals s2” because the first 10 characters match:
#include <stringh>
#include <stdioh>
int main(void)
{
int value;
char *s1, *s2;
s1 = "Opus is a penguin";
s2 = "Opus is a flightless waterfowl";
value = strncmp(s1,s2,10);
if (value<0)
printf("s1 is less than s2\n");
else if (value>0)
printf("s1 is greater than s2\n");
else
printf("s1 equals s2\n");
}
3- 204
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
strncpy
strncpy
The strncpy function copies not more than a specified number of characters from one
string to another.
#include <stringh>
char *strncpy(char *str1_ptr, const char *str2_ptr,
size_t max);
str1_ptr
points to the destination string. *str1_ptr must accommodate at least max characters.
str2_ptr
points to the string to copy.
max
specifies the maximum number of characters to copy; max must be a positive
integer.
Return Value
points to the resulting string.
Usage Guidelines
•
If the length of *str2_ptr is less than max, then *str1_ptr is padded to max length
with null characters. If the length of *str2_ptr is greater than max, then *str1_ptr
will not have a terminating null character.
Example
This example prints the first six characters of s1, “Tandem”:
#include <stringh>
#include <stdioh>
int main(void)
{
char s1[10];
char *s2;
char *s3;
s2 = "Tandem Computers Incorporated";
s3 = strncpy(s1,s2,6);
printf("%s",s3);
/* "Tandem" */
}
Guardian TNS C Library Calls Reference Manual—128833
3 -205
strpbrk
Reference to Library Calls
strpbrk
The strpbrk function scans a string to find the first occurrence of a character from
another string.
#include <stringh>
char *strpbrk(const char *str1_ptr, const char *str2_ptr);
str1_ptr
points to the string to scan.
str2_ptr
points to the string containing the characters to scan for.
Return Value
points to the first occurrence in *str1_ptr of any character in *str2_ptr. If *str1_ptr
does not contain any of the characters in *str2_ptr, then strpbrk returns the pointer
value NULL.
Example
This example scans string s, finds the first common character (-) and prints “-555-1212”:
#include <stringh>
#include <stdioh>
int main(void)
{
char *p;
char *s;
char *b;
s = "800-555-1212";
b = " -"; /* break chars are ' ' and '-' */
p = strpbrk(s,b);
printf("%s",p);
}
3- 206
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
strrchr
strrchr
The strrchr function scans a string backwards for the last occurrence of a given
character.
#include <stringh>
char *strrchr(const char *str_ptr, int chr);
str_ptr
points to the string to scan.
chr
is the character to scan for.
Return Value
points to the last occurrence in *str_ptr of the character chr. If *str_ptr does not
contain chr, then strrchr returns the pointer value NULL.
Example
This example searches string s for the character “a” and prints the character:
#include <stringh>
#include <stdioh>
int main(void)
{
char *p;
char *s;
int c;
c = 'a';
s = "This is an example";
p = strrchr(s, c);
printf("%c", *p);
}
Guardian TNS C Library Calls Reference Manual—128833
3 -207
strspn
Reference to Library Calls
strspn
The strspn function scans a string until it finds a character that is not found in another
specified string.
#include <stringh>
size_t strspn(const char *str1_ptr, const char *str2_ptr);
str1_ptr
points to the string to scan.
str2_ptr
points to the string containing the characters to scan for.
Return Value
is the length of the initial segment of *str1_ptr that consists entirely of characters in
*str2_ptr.
Example
This example scans string s and finds 10 characters before it encounters a character that
is not also in string i:
#include <stringh>
#include <stdioh>
int main(void)
{
size_t length;
char *s;
char *i;
s="An example: how to use strspn";
i="ABCDEFGHIJKLMNOPQRSTUVWXYZ abcdefghijklmnopqrstuvwxyz";
length = strspn(s,i);
printf("%d",length);
/* prints "10" */
}
3- 208
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
strstr
strstr
The strstr function searches a string for the first occurrence of a given substring.
#include <stringh>
char *strstr(const char *str, const char *substr);
str
points to the string to search.
substr
points to the substring to search for.
Return Value
points to the first occurrence in *str of *substr. If the string does not contain the
substring, strstr returns the pointer value NULL. If the length of *substr is zero,
strstr returns str.
Usage Guidelines
•
The strstr function does not include the null character terminating *substr as part of
the substring to search for.
Guardian TNS C Library Calls Reference Manual—128833
3 -209
strtod
Reference to Library Calls
strtod
The strtod function converts the initial portion of a string to a double value.
#include <stdlibh>
double strtod(const char *str_ptr, char **end_ptr_ptr);
str_ptr
points to the string to convert.
end_ptr_ptr
points to the variable of type pointer to char where strtod stores a pointer to the first
unrecognized character in *str_ptr.
Return Value
is the converted double value if the conversion is successful. If strtod could perform
no conversion, it returns zero. If the correctly converted value would cause overflow,
strtod returns positive or negative HUGE_VAL, depending on the sign of the value,
and sets errno to ERANGE (a range error). If the converted value would cause
underflow, strtod returns zero and sets errno to ERANGE.
Usage Guidelines
•
•
•
3- 210
The strtod function scans for a valid floating-point constant, except that the constant
can have no float or long suffix.
The strtod function skips all leading space characters (as defined by isspace) in
*str_ptr.
The strtod function halts scanning when it encounters an unrecognized character.
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
strtok
strtok
The strtok function gets a token from a specified string.
#include <stringh>
char *strtok(char *str1_ptr, const char *str2_ptr);
str1_ptr
is either a pointer to the source string for the first token or a null pointer for
subsequent tokens.
str2_ptr
points to a string that specifies the list of token delimiter characters; these characters
cannot be part of a token.
Return Value
points to the next token in the string. strtok returns the pointer value NULL when
there are no remaining tokens.
Usage Guidelines
•
•
•
The first call to strtok returns a pointer to the first character of the first token.
The strtok function writes a null character to *str1_ptr immediately following the
token.
You can return subsequent tokens by passing NULL as the first argument.
Example
This example gets a token from string token:
#include <stringh>
#include <stdioh>
int main(void)
{
char *object, *separators, *token;
object = "alpha = beta + 123;";
separators = " ;"; /* list of token separators */
token = strtok(object, separators);
while (token != NULL)
{
printf("%s\n",token);
token = strtok(NULL, separators);
}
}
Guardian TNS C Library Calls Reference Manual—128833
3 -211
strtol
Reference to Library Calls
strtol
The strtol function converts a string of characters to a long int value using a specified
base.
#include <stdlibh>
long strtol(const char *str_ptr, char **end_ptr_ptr,
int base);
str_ptr
points to the string to convert.
end_ptr_ptr
points to the variable of type pointer to char where strtol stores a pointer to the first
unrecognized character in *str_ptr.
base
specifies the base of the long integer. It can be in the range from 0 to 36. If base is
zero, strtol scans for a valid integer constant, optionally preceded by a sign but
without a suffix.
If base is less than 0, equal to 1, or greater than 36, strtol does not process the input
string. It returns zero and sets end_ptr_ptr to &str_ptr.
For bases greater than 10, strtol interprets the characters a through z (and A through
Z) as digits representing the values 10 through 35.
Return Value
is the converted long value if the conversion is successful. If strtol could perform no
conversion, it returns zero. If the correctly converted value would cause overflow,
strtol returns LONG_MAX or LONG_MIN, depending on the sign of the value, and
sets errno to ERANGE (a range error).
Usage Guidelines
•
•
3- 212
The strtol function skips all leading space characters (as defined by isspace) in
*str_ptr.
The strtol function halts scanning when it encounters an unrecognized character.
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
strtol
Example
This example prints “138051”, which is the decimal equivalent of the hexadecimal
number 21B43:
#include <stdlibh>
#include <stdioh>
int main(void)
{
char *string;
char *end_of_num;
long num;
string = "21B43";
num = strtol(string, &end_of_num, 16);
printf("%ld",num);
}
Guardian TNS C Library Calls Reference Manual—128833
3 -213
strtoul
Reference to Library Calls
strtoul
The strtoul function converts a string of characters to an unsigned long int value using a
specified base.
#include <stdlibh>
unsigned long strtoul(const char *str_ptr, char
**end_ptr_ptr,
int base);
str_ptr
points to the string to convert.
end_ptr_ptr
points to the variable of type pointer to char where strtoul stores a pointer to the first
unrecognized character in *str_ptr.
base
specifies the base of the long integer. It can be in the range from 0 to 36. If base is
zero, strtoul scans for a valid integer constant, optionally preceded by a sign but
without a suffix.
If base is less than 0, equal to 1, or greater than 36, strtoul does not process the input
string. It returns zero and sets end_ptr_ptr to &str_ptr.
For bases greater than 10, strtoul interprets the characters a through z (and A
through Z) as digits representing the values 10 through 35.
Return Value
is the converted unsigned long value if the conversion is successful. If strtoul could
perform no conversion, it returns zero. If the correctly converted value would cause
overflow, strtoul returns ULONG_MAX and sets errno to ERANGE (a range error).
Usage Guidelines
•
•
3- 214
The strtoul function skips all leading space characters (as defined by isspace) in
*str_ptr.
The strtoul function halts scanning when it encounters an unrecognized character.
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
strxfrm
strxfrm
The strxfrm function “transforms” a string into another such that the strcmp function can
be used to correctly compare two “transformed” strings. The result is the same as if the
strcoll function had been used on the original strings.
#include <stringh>
size_t strxfrm(char *s1, const char *s2, size_t n);
s1
points to an array that will contain the transformed string. If n is zero, s1 is
permitted to be a null pointer.
s2
points to an array that contains the string that the strxfrm function will transform.
n
specifies the maximum number of characters that can be placed in the resulting array
pointed to by s1.
Return Value
is the length of the transformed string. This length does not include the terminating
null character. If the value returned is n or more, the contents of the array pointed to
by s1 are undefined.
Usage Guidelines
•
If s1 and s2 overlap, the result of s1 is undefined.
Guardian TNS C Library Calls Reference Manual—128833
3 -215
stscmp (supplementary)
Reference to Library Calls
stscmp (supplementary)
The stscmp function compares two strings. See “strcmp” on page 3-194 for an
equivalent ISO C Standard function.
#include <stringh>
int stscmp(char *str1_ptr, char *str2_ptr);
str1_ptr
points to the first of the two strings to compare.
str2_ptr
points to the second of the two strings to compare.
Return Value
is zero if the two strings are equal, a negative value if *str1_ptr is less than
*str2_ptr, or a positive value if *str1_ptr is greater than *str2_ptr.
Usage Guidelines
•
3- 216
If two strings are different lengths but match to the end of the shorter string, the
shorter string is considered less than the longer string.
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
system
system
The system function sends a string of characters to the TACL command process for
execution.
#include <stdlib.h>
int system(const char *string);
string
points to an array of characters.
Return Value
is 0 if the system function sends a string and no error occurs. A non-zero return
value other than 1 indicates that a Guardian error occurred.
If the system function is called with string being a null pointer, the return value is 1,
which indicates that the system function is implemented.
Usage Guidelines
•
The first time the system function is invoked, a TACL process is started with a null
OUT file and the current default volume and subvolume names. The current default
volume and subvolume names are used by the C run-time library to expand all
partial file names. This default can be changed with the chvol function.
The TACL process continues to service calls to the system function. Thus, by
making successive calls to the system function, you can establish a context for the
TACL command processor.
Guardian TNS C Library Calls Reference Manual—128833
3 -217
tan
Reference to Library Calls
tan
The tan function computes the tangent of its argument.
#include <mathh>
double tan(double expr);
expr
specifies an angle in radians.
Return Value
is the tangent of expr.
Example
This example prints “The tangent is 1.000004.”:
#include <mathh>
#include <stdioh>
int main(void)
{
double x;
x = 0.7854;
printf("The tangent is %f.", tan(x));
}
3- 218
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
tanh
tanh
The tanh function computes the hyperbolic tangent of its argument.
#include <mathh>
double tanh(double expr);
expr
is any valid expression.
Return Value
is the hyperbolic tangent of expr.
Example
This example prints “The hyperbolic tangent is 0.655795.”:
#include <mathh>
#include <stdioh>
int main(void)
{
double r, x;
x = 0.7854;
r = tanh(x);
printf("The hyperbolic tangent is %f.", r);
}
Guardian TNS C Library Calls Reference Manual—128833
3 -219
terminate_program (supplementary)
Reference to Library Calls
terminate_program (supplementary)
The terminate_program function writes to open files any data left in the buffers, closes
files, passes all of the allowed information to the Guardian system procedure
PROCESS_STOP_, and terminates execution of your C program.
#include <stdlibh>
void terminate_program(short
short
short
short
short
char
short
dummy,
options,
completion_code,
termination_info,
*SPI_ssid,
*text,
text_length);
dummy
is always a zero.
options
specifies whether the process is being stopped because of a normal or abnormal
condition. Specify zero for normal termination (STOP). Specify 1 for abnormal
termination (ABEND). The default is zero.
completion_code
is the completion code to be returned to the parent process in the process deletion
system message. Specify this parameter only if the calling process is terminating
itself and you want to return a completion code value other than the default of zero
(STOP) or 5 (ABEND).
termination_info
specifies the Subsystem Programmatic Interface (SPI) error number that identifies
what caused the process to stop itself. For more information on SPI error numbers
and subsystem IDs, refer to the SPI Programming Manual. If termination_info is not
specified, the default is zero.
SPI_ssid
is a subsystem ID (SSID) that identifies the subsystem defining termination_info.
The format and use of the SSID is described in the SPI Programming Manual.
text
if present and text_length is not zero, is a string of ASCII text to be sent as part of
the process deletion system message.
3- 220
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
terminate_program (supplementary)
text_length
if used, the value of text must be exactly text_length bytes long. The maximum
length is 80 bytes.
Usage Guidelines
•
•
•
The terminate_program function is similar to the exit function but allows you to pass
all of the allowed information to the Guardian system procedure PROCESS_STOP_.
For active backup process pairs, if the primary process calls exit and specifies
normal termination (the option value is zero), both the primary and backup
processes terminate.
In order to ensure that all cleanup operations that the C library needs to perform are
done, it is important that you do not call the Guardian system procedures STOP,
ABEND, or PROCESS_STOP_ directly to terminate your program.
However, STOP should only be replaced with terminate_program when your process
wants to stop itself. For stopping another process, you still use the STOP or
PROCESS_STOP procedure.
•
Descriptions of all of the parameters for the terminate_program function, except for
dummy, are identical to the corresponding parameters for the PROCESS_STOP_
system procedure. See the Guardian Procedure Calls Reference Manual for further
information.
Guardian TNS C Library Calls Reference Manual—128833
3 -221
time
Reference to Library Calls
time
The time function determines the current calendar time, expressed as the number of
seconds that have elapsed since January 1, 1970, Coordinated Universal Time (UTC).
#include <timeh>
time_t time(time_t *timer);
timer
is a pointer. If timer is not NULL, the current calendar time also gets stored in the
variable pointed to by timer.
Return Value
is the current calendar time.
Example
This example uses the time function to obtain the current time in time_t format, then
displays the time.
#include <timeh>
#include <stdioh>
time_t
now;
int main(void)
{
now = time(NULL);
printf("%s%ld\n", "now = ", now);
}
3- 222
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
tmpnam
tmpfile
The tmpfile function creates a temporary C binary file, opening it for ANSI I/O and
binary update access (“wb+”). This temporary file is automatically removed when it is
closed or when the program terminates.
#include <stdioh>
FILE *tmpfile(void);
Return Value
points to the FILE structure denoting the opened temporary file if the operation is
successful; otherwise, tmpfile returns the pointer value NULL.
tmpnam
The tmpnam function produces a valid file name that differs from all file names in the
default volume and subvolume; consequently, you can use this name to create a new file.
#include <stdioh>
char *tmpnam(char *name_buf);
name_buf
is either the pointer value NULL or a pointer to an array of char that can
accommodate at least L_tmpnam (defined in <stdioh>) characters. If name_buf is
NULL, tmpnam stores the file name it generates in an internal buffer; otherwise,
tmpnam stores the file name in the buffer starting at *name_buf.
Return Value
points to the buffer containing the generated file name if the operation is successful;
otherwise, tmpnam returns the pointer value NULL.
Usage Guidelines
•
The tmpnam function will successfully produce a unique file name at least
TMP_MAX (defined in <stdioh>) times.
Guardian TNS C Library Calls Reference Manual—128833
3 -223
toascii (supplementary)
Reference to Library Calls
toascii (supplementary)
The toascii function determines the ASCII equivalent of a nonASCII character.
#include <ctypeh>
int toascii(int character);
character
is the character whose ASCII value you desire.
Return Value
is the ASCII equivalent of character.
Usage Guidelines
•
If character is already an ASCII value, toascii simply returns it unchanged;
otherwise, toascii converts character to an unsigned char, sets the high-order bit to
zero, and returns that value.
Usage Guidelines
•
•
3- 224
The character-testing routine toascii is implemented as a macro, but the C compiler
provides an underlying function with the same name as the macro. Although the
macro is faster than the function, it evaluates its argument more than once.
Consequently, if you need to provide an expression with side effects as the argument
to this routine, you should undefine the macro so that the C compiler uses the
function instead. For more information about undefining macros, refer to the C/C++
Programmer’s Guide.
The ISO/ANSI C standard does not specify toascii. However, the POSIX.1 standard
and XPG4 specification specify toascii.
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
tolower
tolower
The tolower function determines the lowercase equivalent of an uppercase letter.
#include <ctypeh>
int tolower(int character);
character
is the character whose lowercase equivalent you desire.
Return Value
is the lowercase equivalent of character.
Usage Guidelines
•
•
If character is not an uppercase letter, tolower simply returns it unchanged.
The character-testing routine tolower is implemented as a macro, but the C compiler
provides an underlying function with the same name as the macro. Although the
macro is faster than the function, it evaluates its argument more than once.
Consequently, if you need to provide an expression with side effects as the argument
to this routine, you should undefine the macro so that the C compiler uses the
function instead. For more information about undefining macros, refer to the C/C++
Programmer’s Guide.
Guardian TNS C Library Calls Reference Manual—128833
3 -225
toupper
Reference to Library Calls
toupper
The toupper function determines the uppercase equivalent of a lowercase letter.
#include <ctypeh>
int toupper(int character);
character
is the character whose uppercase equivalent you desire.
Return Value
is the uppercase equivalent of character.
Usage Guidelines
•
•
3- 226
If character is not a lowercase letter, toupper simply returns it unchanged.
The character-testing routine toupper is implemented as a macro, but the C compiler
provides an underlying function with the same name as the macro. Although the
macro is faster than the function, it evaluates its argument more than once.
Consequently, if you need to provide an expression with side effects as the argument
to this routine, you should undefine the macro so that the C compiler uses the
function instead. For more information about undefining macros, refer to the C/C++
Programmer’s Guide.
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
trap_overflows (supplementary)
trap_overflows (supplementary)
The trap_overflows function allows you to control the treatment of arithmetic overflows.
#include <stdlibh>
void trap_overflows(short enable_flag);
enable_flag
is an integer that requests overflow trapping be enabled or disabled. If enable_flag is
nonzero, overflow trapping is enabled. If enable_flag is zero, overflows are ignored.
Return Value
none.
Usage Guidelines
•
•
•
•
If overflow trapping is enabled and an overflow occurs, the program stops executing.
If overflow trapping is disabled and an overflow occurs, the overflow condition is
simply ignored. That is, the program continues executing, but the value resulting
from the calculation is undefined.
The default is overflow trapping enabled.
The trap_overflows function is also defined in the <mathh> header.
Guardian TNS C Library Calls Reference Manual—128833
3 -227
ungetc
Reference to Library Calls
ungetc
The ungetc function pushes a single character back into an input file opened for
ANSI I/O.
#include <stdioh>
int ungetc(int character, FILE *stream);
character
specifies the character to be pushed back into the input stream.
stream
denotes a file opened for ANSI I/O.
Return Value
is character if the operation is successful, or the value EOF if an error occurs.
Usage Guidelines
•
•
•
The EOF value cannot be pushed back.
Only one character can be pushed back between read operations.
The fseek, fflush, and rewind functions nullify the effects of ungetc. If you call
ungetc and then call one of these routines, the next input call does not retrieve the
character pushed back by ungetc.
Example
In this example, the ungetc function pushes the character “a” back onto $a.b.c:
#include <stdioh>
FILE *fp;
int status;
int c;
fp = fopen("$a.b.c", "w");
/* ... */
c = 'a';
status = ungetc(c, fp);
3- 228
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
unlink (supplementary)
unlink (supplementary)
The unlink function purges a disk file. Refer to “remove” on page 3-153 for an
equivalent standard function.
#include <fcntlh>
short unlink(char *file_name);
file_name
points to a string that contains a valid file name.
Return Value
is zero if the operation is successful, or -1 if an error occurs.
Usage Guidelines
•
You can call unlink only for closed files.
Example
This example purges the file $a.b.c:
#include <fcntlh>
short status;
status = unlink("$a.b.c");
Guardian TNS C Library Calls Reference Manual—128833
3 -229
va_arg
Reference to Library Calls
va_arg
The va_arg macro expands to an expression whose value is that of the next argument in
the argument list that contains a variable number of arguments. This expression has the
type you specify in the invocation of va_arg.
#include <stdargh>
<type> va_arg(va_list ap, <type>);
ap
is a variable of type va_list that has been initialized by a previous invocation of the
va_start macro.
<type>
is the name of the expected type of the next argument in the argument list that
contains a variable number of arguments. <type> must be a type name such that the
type pointer to <type> can be created by adding * after <type> (as in <type> *).
Return Value
is an expression of type <type> whose value is that of the next argument in the
argument list that contains a variable number of arguments.
Usage Guidelines
•
•
•
3- 230
Following an invocation of va_start, the first invocation of va_arg expands to the
value of the first argument in the argument list, the second invocation of va_arg
expands to the value of the second argument in the list, and so on.
Once all of the arguments in the argument list have been extracted, subsequent
invocations of va_arg (with the same ap and without an intervening invocation of
va_start) expand to random values.
If <type> differs from the actual type (as passed by the caller of the function) of the
next argument in the list, the return value might be incorrect. All subsequent
invocations of va_arg (with the same ap and without an intervening invocation of
va_start) can produce incorrect values as well.
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
va_end
Example
The function defined in this example uses va_start, va_arg, and va_end to compute the
average of a variable number of double values:
#include <stdargh>
/* ... */
double dbl_average(int count, ...)
{
va_list ap;
double div,avg;
if (count<=0)
return 0.0;
va_start(ap, count);
if (count==1)
{
avg=va_arg(ap, double);
va_end(ap);
return avg;
}
div=count;
for (avg=0.0;count>0;count--)
avg+=va_arg(ap, double);
va_end(ap);
return (avg/div);
}
va_end
The va_end macro enables a normal return from a function that uses a variable number
of arguments.
#include <stdargh>
void va_end(va_list ap);
ap
is a variable of type va_list that has been initialized by a previous invocation of the
va_start macro.
Return Value
none.
Example
The example for the va_arg macro demonstrates the usage of va_end.
Guardian TNS C Library Calls Reference Manual—128833
3 -231
va_start
Reference to Library Calls
va_start
The va_start macro initializes its first argument for use as the retainer of a list that
contains the variable number of arguments. This first argument, ap, can then be used by
va_arg and va_end to extract arguments from the list.
#include <stdargh>
void va_start(va_list ap, <last_parm>);
ap
is the variable of type va_list that va_start initializes for use as a retainer for the list
that contains the variable number of arguments.
<last_parm>
is the identifier of the last parameter in the declaration of the function that is using
the variable number of arguments. This identifier, then, is the name of the parameter
immediately preceding the ellipsis (...) in the function declaration.
Return Value
none.
Usage Guidelines
•
•
•
3- 232
You must invoke va_start before accessing the list that contains the variable number
of arguments.
In the declaration of the function that uses the variable number of arguments, the
parameter <last_parm> cannot have the register storage class.
Successive invocations of va_start reset ap to the first argument in the variable
argument list. This resetting enables a function you write to reuse the arguments in
the list (as the fprintf family of functions does).
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
vfprintf
vfprintf
The vfprintf function writes formatted data to a file opened for ANSI I/O, extracting the
data values from a variable argument list.
#include <stdargh>
#include <stdioh>
int vfprintf(FILE *stream, const char *format, va_list ap);
stream
denotes a file opened for ANSI I/O.
format
points to a string that contains characters and conversion specifiers, which indicate
how to format the values of the arguments denoted by ap. Refer to “fprintf” on
page 3-51 for a description of format and conversion specifiers.
ap
is a variable of type va_list that has been initialized by a previous invocation of
va_start (and possibly invocations of va_arg as well).
Return Value
is the number of characters output if the operation is successful; otherwise, vfprintf
returns a negative value.
Usage Guidelines
•
•
Note that vfprintf requires two headers, <stdargh> and <stdioh>.
The vfprintf function does not call the va_end function.
Guardian TNS C Library Calls Reference Manual—128833
3 -233
vprintf
Reference to Library Calls
vprintf
The vprintf function writes formatted data to the standard output file, extracting the data
values from a variable argument list.
#include <stdargh>
#include <stdioh>
int vprintf(const char *format, va_list ap);
format
points to a string that contains characters and conversion specifiers, which indicate
how to format the values of the arguments denoted by ap. Refer to “fprintf” on
page 3-51 for a description of format and conversion specifiers.
ap
is a variable of type va_list that has been initialized by a previous invocation of
va_start (and possibly invocations of va_arg as well).
Return Value
is the number of characters output if the operation is successful; otherwise, vprintf
returns a negative value.
Usage Guidelines
•
•
3- 234
Note that vprintf requires two headers, <stdargh> and <stdioh>.
The vprintf function does not call the va_end function.
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
vsprintf
vsprintf
The vsprintf function writes formatted data to a string, extracting the data values from a
variable argument list.
#include <stdargh>
#include <stdioh>
int vsprintf(char *str, const char *format, va_list ap);
str
points to the string where vsprintf stores the formatted data.
format
points to a string that contains characters and conversion specifiers, which indicate
how to format the values of the arguments denoted by ap. Refer to “fprintf” on
page 3-51 for a description of format and conversion specifiers.
ap
is an variable of type va_list that has been initialized by a previous invocation of
va_start (and possibly invocations of va_arg as well).
Return Value
is the number of characters output if the operation is successful; otherwise, vsprintf
returns a negative value.
Usage Guidelines
•
•
Note that vsprintf requires two headers, <stdargh> and <stdioh>.
The vsprintf function does not call the va_end function.
Guardian TNS C Library Calls Reference Manual—128833
3 -235
wctomb
Reference to Library Calls
wctomb
The wctomb function converts a wide character to a multibyte character.
#include <stdlibh>
int wctomb(char *s, wchar_t wchar);
s
points to a character array that will contain the multibyte character. This character
array should be at least MB_CUR_MAX characters long.
wchar
is a variable of type wchar_t that contains the wide character that the wctomb
function converts.
Return value
If s is a null pointer, the return value is 0.
If s is not a null pointer, the return value is:
0
if s points to a null character
1
if wchar is an ASCII character
2
if the first byte and the second byte in wchar form a valid 2-byte character
-1 if wchar is not a valid multibyte character
Usage Guidelines
•
The MB_CUR_MAX macro specifies the maximum number of bytes used in
representing a multibyte character in the current locale (category LC_CTYPE). The
MB_CUR_MAX macro is defined in the header stdlibh as:
#define MB_CUR_MAX
•
3- 236
2
The behavior of the wctomb function is affected by the LC_CTYPE category of the
current locale.
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
wcstombs
wcstombs
The wcstombs function converts a sequence of wide characters into a sequence of
multibyte characters.
#include <stdlibh>
size_t wcstombs(char *s, const wchar_t *pwcs, size_t n);
s
points to the array that will hold the multibyte characters.
pwcs
points to the array that contains the sequence of wide characters to be converted.
n
specifies the total number of bytes that can be modified in the array pointed to by s.
Return Value
(size_t) -1 if a wide character is encountered that does not correspond to a valid
multibyte character.
Otherwise, the function returns the number of bytes copied to the array pointed to by
s. If a null terminator is present, it is not included in the count.
Usage Guidelines
•
•
The conversion stops if the sequence of multibyte characters in the array pointed to
by s exceeds the limit of n total bytes or if a null character is encountered.
The behavior of the wcstombs function is affected by the LC_CTYPE category of
the current locale.
Guardian TNS C Library Calls Reference Manual—128833
3 -237
write (supplementary)
Reference to Library Calls
write (supplementary)
The write function writes a specified number of bytes from a buffer to a file opened for
alternate I/O.
#include <fcntlh>
short write(int file_des, char *buf, short nbytes);
file_des
is the descriptor of a file opened for alternate I/O.
buf
points to the buffer to be written.
nbytes
specifies the number of bytes to write from the buffer.
Return Value
is the number of bytes written if the operation is successful, or -1 if an error occurs.
Example
This example reads two bytes from the array named buf and writes them to the file
$a.b.c:
#include <fcntlh>
int filedes;
short status;
short nbytes;
char buf[20];
filedes = open("$a.b.c", O_WRONLY|O_BINARY);
/* ... */
nbytes = 2;
status = write(filedes, buf, nbytes);
3- 238
128833 —Guardian TNS C Library Calls Reference Manual
Reference to Library Calls
writeread (supplementary)
writeread (supplementary)
The writeread function writes a message and then reads the resulting input. More
specifically, writeread:
1. Writes a number of bytes from a buffer to a file
2. Begins to read a number of bytes from the file to the buffer
3. Causes suspension of C program execution until the read operation is complete
4. Returns either the number of bytes that it has read or an end-of-file or error
indication
The file can be a disk file, a terminal, or a process.
#include <fcntlh>
short writeread(short file_des, char *buf, short write_bytes,
short read_bytes);
file_des
is the descriptor of a file opened for alternate I/O.
buf
points to the buffer used both for the write and the subsequent read.
write_bytes
specifies the number of bytes to write from the buffer.
read_bytes
specifies the maximum number of bytes to read into the buffer.
Return Value
is the number of bytes read if the operation is successful. If writeread encounters the
end of the file, it returns zero and sets errno to 1. If an error occurs, writeread returns
-1 and sets errno to the Guardian error number.
Usage Guidelines
•
•
•
You can use the writeread function only with files that are opened for alternate I/O
and read-write access.
You should set errno to zero before each call to writeread.
You can use writeread with both text and binary files. The function appends the data
in buf to any buffered output data and then flushes the buffer.
Guardian TNS C Library Calls Reference Manual—128833
3 -239
writeread (supplementary)
3- 240
Reference to Library Calls
128833 —Guardian TNS C Library Calls Reference Manual
Index
A
abort function 3-1
abs function 3-1
acos function 3-2
ANSI C standard 1-1
asctime function 3-3
asin function 3-5
assert macro 3-6
asserth header 2-1
atan function 3-7
atan2 function 3-8
atexit function 3-9
atof function 3-10
atoi function 3-11
atol function 3-12
B
bsearch function 3-13
C
C run-time library
introduction 1-1
standards compliance 1-1
calloc function 3-14
ceil function 3-15
chvol function 3-16
CLARGE 1-1
clearerr function 3-17
CLIB 1-1
clock function 3-18
close function 3-19
CNONSTOP 1-1
Completion codes 3-31
Conversion codes
for printf family 3-53
for scanf family 3-64
Conversion flags for printf family 3-52
Conversion modifiers
for printf family 3-53
for scanf family 3-63
Conversion specifiers
for printf family 3-51
for scanf family 3-63
cos function 3-20
cosh function 3-21
creat function 3-21
CSMALL 1-1
ctime function 3-22
ctypeh header 2-1
CWIDE 1-1
D
Data-model 1-1
dec_to_longlong function 3-24
difftime function 3-25
div function 3-25
E
ecvt function 3-26
edfseek function 3-27
edftell function 3-29
edlseek function 3-30
errno function 2-2
errnoh header 2-2
exit function 3-31
exp function 3-32
F
fabs function 3-33
Fault-tolerant programming 3-126, 3-128,
3-129, 3-130, 3-132, 3-134
fclose function 3-34
fcloseall function 3-35
Guardian TNS C Library Calls Reference Manual—128833
Index- 1
G
Index
fcntl function 3-35
fcntlh header 2-5
fdopen function 3-37
fdtogfn function 3-38
feof function 3-39
ferror function 3-40
fflush function 3-41
fgetc function 3-42
fgetpos function 3-43
fgets function 3-44
fileno function 3-45
Files, header 2-1
floath header 2-6
floor function 3-46
fmod function 3-47
fopen function 3-48
fopen_std_file function 3-50
Format strings
for printf family 3-51
for scanf family 3-62
fprintf function 3-51
fputc function 3-55
fputs function 3-56
fread function 3-57
free function 3-58
freopen function 3-59
frexp function 3-61
fscanf function 3-61
fseek function 3-66
fsetpos function 3-67
ftell function 3-68
fwrite function 3-69
get_assign_msg_by_name function 3-73
get_param_by_name function 3-76
get_param_msg function 3-78
get_startup_msg function 3-79
gmtime function 3-85
G
L
getc function 3-82
getchar function 3-82
getenv function 3-83
gets function 3-84
get_assign_msg function 3-70
labs function 3-102
ldexp function 3-103
ldiv function 3-104
Index- 2
H
Header files 2-1
heap_check function 3-86
heap_check_always function 3-86
heap_min_block_size function 3-87
I
int data type
16 bits 2-8
32 bits 2-8
isalnum function 3-88
isalpha function 3-89
isascii function 3-90
iscntrl function 3-91
iscsym function 3-92
iscsymf function 3-93
isdigit function 3-94
isgraph function 3-95
islower function 3-96
ISO C standard 1-1
isprint function 3-97
ispunct function 3-98
isspace function 3-99
isupper function 3-100
isxdigit function 3-101
is_system_trap function 3-87
128833 —Guardian TNS C Library Calls Reference Manual
Index
P
Library
asserth header 2-1
ctypeh header 2-1
errnoh header 2-2
fcntlh header 2-5
floath header 2-6
headers 2-1
limitsh header 2-8
localeh header 2-9
mathh header 2-9
memoryh header 2-10
nonstoph header 2-10
setjmph header 2-10
signalh header 2-10
sqlh header 2-11
stdargh header 2-11
stddefh header 2-11
stdioh header 2-11
stdlibh header 2-12
stringh header 2-13
talh header 2-13
timeh header 2-13
limitsh header 2-8
localeconv function 3-105
localeh header 2-9
localtime function 3-106
log function 3-106
log10 function 3-107
longjmp function 3-108
longlong_to_dec function 3-109
lseek function 3-111
memchr function 3-117
memcmp function 3-118
memcpy function 3-119
memmove function 3-120
memoryh header 2-10
Memory-model 1-1
memset function 3-120
memswap function 3-121
min macro 3-122
mktime function 3-123
Model-dependent libraries 1-1
modf function 3-125
movmem function 3-126
M
perror function 3-139
pow function 3-140
printf function 3-141
ptrdiff_t 2-11
putc function 3-143
putchar function 3-144
putenv function 3-145
puts function 3-146
malloc function 3-112
mathh header 2-9
max macro 3-113
mblen 3-114
mbstowcs 3-115
mbtowc 3-116
N
NDEBUG macro 3-6
nonstoph header 2-10
ns_backup_fopen function 3-126
ns_fget_file_open_state function 3-128
ns_fget_file_state function 3-129
ns_fopen_special function 3-130
ns_fset_file_state function 3-132
ns_start_backup function 3-134
NULL 2-11
O
offsetof 2-11
offsetof macro 3-136
open function 3-137
P
Guardian TNS C Library Calls Reference Manual—128833
Index- 3
Q
Q
qsort function 3-147
R
raise function 3-148
rand function 3-149
read function 3-150
readupdate function 3-150
realloc function 3-152
remove function 3-153
rename function 3-153
reply function 3-154
repmem function 3-155
rewind function 3-156
Run-time libraries 1-1
S
scanf function 3-157
SEEK_CUR macro
used in edfseek 3-28
used in edlseek 3-30
used in fseek 3-66
used in lseek 3-111
SEEK_END macro
used in edfseek 3-28
used in edlseek 3-30
used in fseek 3-66
used in lseek 3-111
SEEK_SET macro
used in edfseek 3-28
used in edlseek 3-30
used in fseek 3-66
used in lseek 3-111
setbuf function 3-158
setjmp function 3-159
setjmph header 2-10
setlocale function 3-160
setmem function 3-161
Index- 4
Index
setnbuf function 3-162
setvbuf function 3-162
signal function 3-164
signalh header 2-10
sin function 3-167
sinh function 3-168
size_t 2-11
sprintf function 3-169
sqlh header 2-11
sqrt function 3-170
srand function 3-171
sscanf function 3-172
Standards compliance 1-1
stcarg function 3-174
stccpy function 3-175
stcd_i function 3-176
stcd_l function 3-177
stch_i function 3-178
stcis function 3-180
stcisn function 3-181
stci_d function 3-179
stclen function 3-182
stcpm function 3-182
stcpma function 3-184
stcu_d function 3-186
stdargh header 2-11
stddefh header 2-11
stdioh header 2-11
stdlibh header 2-12
stpblk function 3-187
stpbrk function 3-188
stpchr function 3-188
stpsym function 3-189
stptok function 3-191
strcat function 3-192
strchr function 3-193
strcmp function 3-194
strcoll function 3-195
strcpy function 3-196
128833 —Guardian TNS C Library Calls Reference Manual
Index
strcspn function 3-197
strerror function 3-198
strftime function 3-199
stringh header 2-13
strlen function 3-201
strncat function 3-202
strncmp function 3-203
strncpy function 3-205
strpbrk function 3-206
strrchr function 3-207
strspn function 3-208
strstr function 3-209
strtod function 3-210
strtok function 3-211
strtol function 3-212
strtoul function 3-214
strxfrm function 3-215
stscmp function 3-216
system function 3-217
T
talh header 2-13
tan function 3-218
tanh function 3-219
terminate_program function 3-220
time function 3-222
timeh header 2-13
tmpfile function 3-223
tmpnam function 3-223
toascii function 3-224
tolower function 3-225
toupper function 3-226
trap_overflows function 3-227
Special Characters
V
va_arg macro 3-230
va_end macro 3-231
va_start macro 3-232
vfprintf function 3-233
vprintf function 3-234
vsprintf function 3-235
W
wcstombs function 3-237
wctomb 3-236
write function 3-238
writeread function 3-239
Special Characters
_is_system_trap function 3-87
_max macro 3-113
_min macro 3-122
__ns_backup_fopen function 3-126
__ns_fget_file_open_state function 3-128
__ns_fget_file_state function 3-129
__ns_fopen_special function 3-130
__ns_fset_file_state function 3-132
__ns_start_backup function 3-134
U
ungetc function 3-228
unlink function 3-229
Guardian TNS C Library Calls Reference Manual—128833
Index- 5
Special Characters
Index- 6
Index
128833 —Guardian TNS C Library Calls Reference Manual