Cn Standard Library Reference Manual 3.1 Rev3.A

8/22/2019 Cn Standard Library Reference Manual 3.1 Rev3.A

1/605

Cn Standard Libraries

Reference Manual

Document No. 06-RM-1139 Revision: 3.A

14 August 2008

Build 1.253.1.44


2/605


3/605


Document No. 06-RM-1139 Revision: 3.00 3

ClearSpeed Technology plc

Contents

1 ANSI C Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

1.1 Standard Utility Functions (stdlib.h, stdlibp.h) . . . . . . . . . . . . . . . . . . 22

_Exit end program execution with no cleanup processing . . . . . . . . 23

a64l,l64a convert between radix-64 ascii string and long . . . . . . . . 24

abort abnormal termination of a program . . . . . . . . . . . . . . . . . . . . . 25

abs integer absolute value (magnitude) . . . . . . . . . . . . . . . . . . . . . . . 26

assert Macro for Debugging Diagnostics . . . . . . . . . . . . . . . . . . . . . 27

atof, atoff string to double or float . . . . . . . . . . . . . . . . . . . . . . . . . 28

atoi, atol string to integer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

calloc allocate space for arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

div divide two integers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

ecvtbuf, fcvtbuf double or float to string . . . . . . . . . . . . . . . . . . . . 32

ecvt,ecvtf,fcvt,fcvtf double or float to string . . . . . . . . . . . . . . . 33

gvcvt, gcvtf format double or float as string . . . . . . . . . . . . . . . . . . 34

exit end program execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

labs long integer absolute value . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

ldiv divide two long integers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37malloc, realloc, free manage memory . . . . . . . . . . . . . . . . . . . . 38

mblen minimal multibyte length function . . . . . . . . . . . . . . . . . . . . . . . 39

_mblen_r reentrant minimal multibyte length function . . . . . . . . . . . . 40

mbstowcs minimal multibyte string to wide char converter . . . . . . . . 41

mbtowc minimal multibyte to wide char converter . . . . . . . . . . . . . . . . 42

mallinfo, malloc_stats--malloc support . . . . . . . . . . . . . . . . . . . . . 43

rand, srand pseudo-random numbers . . . . . . . . . . . . . . . . . . . . . . . 44

rand48, drand48, erand48, lrand48, nrand48, mrand48, jrand48,srand48, seed48, lcong48 pseudo random number generators andinitialization routines 45

strtod, strtof string to double or float . . . . . . . . . . . . . . . . . . . . . . 47

strtol string to long . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

strtoul string to unsigned long . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

wcstombs minimal wide char string to multibyte string converter . . . . 50

wctomb minimal wide char to multibyte converter . . . . . . . . . . . . . . . . 51


4/605


4 Document No. 06-RM-1139 Revision: 3.00


a64lp,l64ap convert between radix-64 ascii string and long . . . . . . 52

absp integer absolute value (magnitude) . . . . . . . . . . . . . . . . . . . . . . 53

assertp Macro for Debugging Diagnostics . . . . . . . . . . . . . . . . . . . . 54

atofp, atoffp string to double or float . . . . . . . . . . . . . . . . . . . . . . . 55

atoip string to integer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

divp divide two integers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

ecvtbufp, fcvtbufp double or float to string . . . . . . . . . . . . . . . . . . 58

ecvtp,ecvtfp,fcvtp,fcvtfp double or float to string . . . . . . . . . . . 59

gvcvtp, gcvtfp format double or float as string . . . . . . . . . . . . . . . . 60

labsp long integer absolute value . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

ldivp divide two long integers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

mblenp minimal multibyte length function . . . . . . . . . . . . . . . . . . . . . . 63

_mblenp_r reentrant minimal multibyte length function . . . . . . . . . . . 64

mbstowcsp minimal multibyte string to wide char converter . . . . . . . 65

mbtowcp minimal multibyte to wide char converter . . . . . . . . . . . . . . 66

rand48p, drand48p, erand48p, lrand48p, nrand48p, mrand48p,jrand48p, srand48p, seed48p, lcong48p pseudo random numbergenerators and initialization routines 67

randp, srandp pseudo-random numbers . . . . . . . . . . . . . . . . . . . . . 69

strtolp string to long . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70strtoulp string to unsigned long . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

wcstombs minimal wide char string to multibyte string converter . . . . 72

wctombp minimal wide char to multibyte converter . . . . . . . . . . . . . . 73

1.1.1 Memory usage in stdlib (mono) functions (excluding underlying functions and

stack usage) 74

1.1.2 Memory usage in stdlibp (poly) functions (excluding underlying functions and

stack usage) 75

1.2 Character Type Functions and Macros (ctype.h, ctypep.h) . . . . . . . . 77

isalnum alphanumeric character predicate . . . . . . . . . . . . . . . . . . . . 78

isalpha alphabetic character predicate . . . . . . . . . . . . . . . . . . . . . . 79

isascii ASCII character predicate . . . . . . . . . . . . . . . . . . . . . . . . . . 80

isblank blank character predicate . . . . . . . . . . . . . . . . . . . . . . . . . . 81

iscntrl control character predicate . . . . . . . . . . . . . . . . . . . . . . . . . 82

isdigit decimal digit predicate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

islower lower-case character predicate . . . . . . . . . . . . . . . . . . . . . . 84


5/605




isprint, isgraph printable character predicates . . . . . . . . . . . . . . 85

ispunct punctuation character predicate . . . . . . . . . . . . . . . . . . . . . 86

isspace whitespace character predicate . . . . . . . . . . . . . . . . . . . . . . 87

isupper uppercase character predicate . . . . . . . . . . . . . . . . . . . . . . 88

isxdigit hexadecimal digit predicate . . . . . . . . . . . . . . . . . . . . . . . . 89

toascii force integers to ASCII range . . . . . . . . . . . . . . . . . . . . . . . 90

tolower translate characters to lower case . . . . . . . . . . . . . . . . . . . . 91

toupper translate characters to upper case . . . . . . . . . . . . . . . . . . . 92

isalnump alphanumeric character predicate . . . . . . . . . . . . . . . . . . . 93

isalphap alphabetic character predicate . . . . . . . . . . . . . . . . . . . . . 94

isasciip ASCII character predicate . . . . . . . . . . . . . . . . . . . . . . . . . 95

isblankp blank character predicate . . . . . . . . . . . . . . . . . . . . . . . . . 96

iscntrlp control character predicate . . . . . . . . . . . . . . . . . . . . . . . . 97

isdigitp decimal digit predicate . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

islowerp lower-case character predicate . . . . . . . . . . . . . . . . . . . . . 99

isprintp, isgraphp printable character predicates . . . . . . . . . . . 100

ispunctp punctuation character predicate . . . . . . . . . . . . . . . . . . . 101

isspacep whitespace character predicate . . . . . . . . . . . . . . . . . . . . 102

isupperp uppercase character predicate . . . . . . . . . . . . . . . . . . . . 103

isxdigitp hexadecimal digit predicate . . . . . . . . . . . . . . . . . . . . . . 104

toasciip force integers to ASCII range . . . . . . . . . . . . . . . . . . . . . 105

tolowerp translate characters to lower case . . . . . . . . . . . . . . . . . . 106

toupperp translate characters to upper case . . . . . . . . . . . . . . . . . 107

1.2.1 Memory usage in ctype (mono) functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

1.2.2 Memory usage in ctypep (poly) functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

1.3 Standard Input and Output (stdio.h, stdiop.h) . . . . . . . . . . . . . . . . . . .110

putchar write a character . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

puts write a character string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

printf, sprintf format output . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

putcharp write a character . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

putsp write a character string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

printfp, sprintfp format output . . . . . . . . . . . . . . . . . . . . . . . . . 119

1.3.1 Memory usage in stdio (mono) functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

1.3.2 Memory usage in stdlibp (poly) functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 123


6/605




1.4 String and Memory Functions (string.h, stringp.h) . . . . . . . . . . . . . . 124

bcmp compare two memory areas . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

bcopy copy memory regions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

bzero initialize memory to zero . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

index search for character in string . . . . . . . . . . . . . . . . . . . . . . . . . 128

memccpy copy memory regions with end-token check . . . . . . . . . . . 129

memchr find character in memory . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

memcmp compare two memory areas . . . . . . . . . . . . . . . . . . . . . . . . 131

memcpy copy memory regions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

memmove move possibly overlapping memory . . . . . . . . . . . . . . . . . 133

mempcpy copy memory regions and return end pointer . . . . . . . . . . 134

memset set an area of memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

rindex reverse search for character in string . . . . . . . . . . . . . . . . . 136

strcasecmp case insensitive character string compare . . . . . . . . . 137

strcat concatenate strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

strchr search for character in string . . . . . . . . . . . . . . . . . . . . . . . . 139

strcmp character string compare . . . . . . . . . . . . . . . . . . . . . . . . . . . 140

strcoll locale specific character string compare . . . . . . . . . . . . . . 141

strcpy copy string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

strcspn count chars not in string . . . . . . . . . . . . . . . . . . . . . . . . . . 143

strerror convert error number to string . . . . . . . . . . . . . . . . . . . . . 144

strerror_r convert error number to string and copy to buffer . . . . 150

strlen character string length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151

strlwr force string to lower case . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

strncasecmp case insensitive character string compare . . . . . . . . 153

strncat concatenate strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

strncmp character string compare . . . . . . . . . . . . . . . . . . . . . . . . . . 155strncpy counted copy string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

strnlen character string length . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

strpbrk find chars in string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

strrchr reverse search for character in string . . . . . . . . . . . . . . . . 159

strspn find initial match . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160

strstr find string segment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161


7/605




strtok,strtok_r,strsep get next token from a string . . . . . . . . . 162

strupr force string to uppercase . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

strxfrm transform string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164

swab swap adjacent bytes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

bcmpp compare two memory areas . . . . . . . . . . . . . . . . . . . . . . . . . 166

bcopyp copy memory regions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

bzerop initialize memory to zero . . . . . . . . . . . . . . . . . . . . . . . . . . . 168

indexp search for character in string . . . . . . . . . . . . . . . . . . . . . . . . 169

memccpyp copy memory regions with end-token check . . . . . . . . . . 170

memchrp find character in memory . . . . . . . . . . . . . . . . . . . . . . . . . . 171

memcmpp compare two memory areas . . . . . . . . . . . . . . . . . . . . . . . 172

memcpyp, memcpypp copy memory regions . . . . . . . . . . . . . . . . . . . 173

memmovep move possibly overlapping memory . . . . . . . . . . . . . . . . 174

mempcpyp copy memory regions and return end pointer . . . . . . . . . 175

memsetp set an area of memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

rindexp reverse search for character in string . . . . . . . . . . . . . . . . 177

strpbrkp find chars in string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178

strcasecmpp case insensitive character string compare . . . . . . . . 179

strcatp concatenate strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180

strchrp search for character in string . . . . . . . . . . . . . . . . . . . . . . . 181

strcmpp character string compare . . . . . . . . . . . . . . . . . . . . . . . . . . 182

strcollp locale specific character string compare . . . . . . . . . . . . . 183

strcpyp copy string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184

strcspnp count chars not in string . . . . . . . . . . . . . . . . . . . . . . . . . 185

strerrorp convert error number to string . . . . . . . . . . . . . . . . . . . . 186

strerrorp_r convert error number to string and copy to buffer . . . 192

strlenp character string length . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193strlwrp force string to lower case . . . . . . . . . . . . . . . . . . . . . . . . . . 194

strncasecmpp case insensitive character string compare . . . . . . . 195

strncatp concatenate strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196

strncmpp character string compare . . . . . . . . . . . . . . . . . . . . . . . . . 197

strncpyp counted copy string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198

strnlenp character string length . . . . . . . . . . . . . . . . . . . . . . . . . . . 199


8/605




strrchrp reverse search for character in string . . . . . . . . . . . . . . . 200

strspnp find initial match . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

strstrp find string segment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202

strtokp,strtokp_r,strsepp get next token from a string . . . . . . 203

struprp force string to uppercase . . . . . . . . . . . . . . . . . . . . . . . . . . 204

strxfrmp transform string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205

swabp swap adjacent bytes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206

1.4.1 Memory usage in string (mono) functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 207

1.4.2 Memory usage in stringp (poly) functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

1.5 Wide Character Strings (wchar.h, wcharp.h) . . . . . . . . . . . . . . . . . . . 210

wcscat concatenate two wide-character strings . . . . . . . . . . . . . . . 211

wcschr wide-character string scanning operation . . . . . . . . . . . . . . 212

wcscmp compare two wide-character strings . . . . . . . . . . . . . . . . . . 213

wcscoll locale specific wide-character string compare . . . . . . . . . . 214

wcscpy copy a wide-character string . . . . . . . . . . . . . . . . . . . . . . . . 215

wcscspn get length of a complementary wide substring . . . . . . . . . 216

wcslcat concatenate wide-character strings to specified length . . . 217

wcslcpy copy a wide-character string to specified length . . . . . . . . 218

wcslen get wide-character string length . . . . . . . . . . . . . . . . . . . . . . 219

wcsncat concatenate part of two wide-character strings . . . . . . . . . 220

wcsncmp compare part of two wide-character strings . . . . . . . . . . . . 221

wcsncpy copy part of a wide-character string . . . . . . . . . . . . . . . . . 222

wcsnlen get fixed-size wide character string length . . . . . . . . . . . . 223

wcspbrk -scan wide-character string for a wide-character code . . . 224

wcsrchr wide-character string scanning operation . . . . . . . . . . . . . 225

wcsspn get length of a wide substring . . . . . . . . . . . . . . . . . . . . . . . 226

wcsstr find a wide-character substring . . . . . . . . . . . . . . . . . . . . . . 227

wcswidth number of column positions of a wide-character string . . 228

wcwidth number of column positions of a wide-character code . . . 229

wmemchr find a wide-character in memory . . . . . . . . . . . . . . . . . . . . 230

wmemcmp compare wide-characters in memory . . . . . . . . . . . . . . . . 231

wmemcpy copy wide-characters in memory . . . . . . . . . . . . . . . . . . . . 232

wmemmove wmemmove - copy wide-characters in memory withoverlapping areas 233


9/605




wmemset set wide-characters in memory . . . . . . . . . . . . . . . . . . . . . 234

wcscatp concatenate two wide-character strings . . . . . . . . . . . . . . 235

wcschrp wide-character string scanning operation . . . . . . . . . . . . . 236

wcscmpp compare two wide-character strings . . . . . . . . . . . . . . . . . 237

wcscollp locale specific wide-character string compare . . . . . . . . . 238

wcscpyp copy a wide-character string . . . . . . . . . . . . . . . . . . . . . . . 239

wcscspnp get length of a complementary wide substring . . . . . . . . 240

wcslcatp concatenate wide-character strings to specified length . . 241

wcslcpyp copy a wide-character string to specified length . . . . . . . 242

wcslenp get wide-character string length . . . . . . . . . . . . . . . . . . . . 243

wcsncatp concatenate part of two wide-character strings . . . . . . . . 244

wcsncmpp compare part of two wide-character strings . . . . . . . . . . . 245

wcsncpyp copy part of a wide-character string . . . . . . . . . . . . . . . . 246

wcsnlenp get fixed-size wide character string length . . . . . . . . . . . 247

wcspbrkp -scan wide-character string for a wide-character code . . 248

wcsrchrp wide-character string scanning operation . . . . . . . . . . . . 249

wcsspnp get length of a wide substring . . . . . . . . . . . . . . . . . . . . . . 250

wcsstrp find a wide-character substring . . . . . . . . . . . . . . . . . . . . . 251

wcswidthp number of column positions of a wide-character string . 252

wcwidthp number of column positions of a wide-character code . . 253

wmemchrp find a wide-character in memory . . . . . . . . . . . . . . . . . . . 254

wmemcmpp compare wide-characters in memory . . . . . . . . . . . . . . . 255

wmemcpyp copy wide-characters in memory . . . . . . . . . . . . . . . . . . . 256

wmemmovep wmemmovep - copy wide-characters in memory withoverlapping areas 257

wmemsetp set wide-characters in memory . . . . . . . . . . . . . . . . . . . . 258

1.5.1 Memory usage in wchar (mono) functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 259

1.5.2 Memory usage in wcharp (poly) functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 260

1.6 Wide Character Types (wctype.h, wctypep.h) . . . . . . . . . . . . . . . . . . 261

iswalnum alpha-numeric wide-character test . . . . . . . . . . . . . . . . . 262

iswalpha alphabetic wide-character test . . . . . . . . . . . . . . . . . . . . . 263

iswblank wide-character blank test . . . . . . . . . . . . . . . . . . . . . . . . 264

iswcntrl wide-character cntrl test . . . . . . . . . . . . . . . . . . . . . . . . . 265

iswctype extensible wide-character test . . . . . . . . . . . . . . . . . . . . . 266


10/605




iswdigit decimal digit wide-character test . . . . . . . . . . . . . . . . . . . 267

iswgraph graphic wide-character test . . . . . . . . . . . . . . . . . . . . . . . 268

iswlower lower-case wide-character test . . . . . . . . . . . . . . . . . . . . 269

iswprint printable wide-character test . . . . . . . . . . . . . . . . . . . . . . 270

iswpunct punctuation wide-character test . . . . . . . . . . . . . . . . . . . 271

iswspace wide-character space test . . . . . . . . . . . . . . . . . . . . . . . . 272

iswupper upper-case wide-character test . . . . . . . . . . . . . . . . . . . . 273

iswxdigit hexadecimal digit wide-character test . . . . . . . . . . . . . . 274

towctrans extensible wide-character case mapping . . . . . . . . . . . 275

towlower translate wide-characters to lower case . . . . . . . . . . . . . 276

towupper translate wide-characters to upper case . . . . . . . . . . . . . 277

wctrans get wide-character translation type . . . . . . . . . . . . . . . . . . 278

wctype get wide-character classification type . . . . . . . . . . . . . . . . . 279

iswalnump alpha-numeric wide-character test . . . . . . . . . . . . . . . . 280

iswalphap alphabetic wide-character test . . . . . . . . . . . . . . . . . . . 281

iswblankp wide-character blank test . . . . . . . . . . . . . . . . . . . . . . . 282

iswcntrlp wide-character cntrl test . . . . . . . . . . . . . . . . . . . . . . . . 283

iswctypep extensible wide-character test . . . . . . . . . . . . . . . . . . . . 284

iswdigitp decimal digit wide-character test . . . . . . . . . . . . . . . . . . 285

iswgraphp graphic wide-character test . . . . . . . . . . . . . . . . . . . . . . 286

iswlowerp lower-case wide-character test . . . . . . . . . . . . . . . . . . . 287

iswprint printable wide-character test . . . . . . . . . . . . . . . . . . . . . . 288

iswpunctp punctuation wide-character test . . . . . . . . . . . . . . . . . . 289

iswspacep wide-character space test . . . . . . . . . . . . . . . . . . . . . . . 290

iswupperp upper-case wide-character test . . . . . . . . . . . . . . . . . . . 291

iswxdigitp hexadecimal digit wide-character test . . . . . . . . . . . . . 292

towctransp extensible wide-character case mapping . . . . . . . . . . 293towlowerp translate wide-characters to lower case . . . . . . . . . . . . 294

towupperp translate wide-characters to upper case . . . . . . . . . . . . 295

wctransp get wide-character translation type . . . . . . . . . . . . . . . . . 296

wctypep get wide-character classification type . . . . . . . . . . . . . . . . 297

1.7 Locale Functions (locale.h) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298

setlocale, localeconv select or query locale . . . . . . . . . . . . . . . 300


11/605




2 The Red Hat newlib C Math Library . . . . . . . . . . . . . . . . . . . . . . . . . . 301

2.1 Use of poly memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301

2.2 Mathematical functions (math.h, mathp.h) . . . . . . . . . . . . . . . . . . . . 303

cbrt, cbrtf cube root . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304

copysign, copysignf sign ofy, magnitude ofx . . . . . . . . . . . . . . 305

expm1, expm1f exponential minus 1 . . . . . . . . . . . . . . . . . . . . . . . . 306

ilogb, ilogbf get exponent of floating-point number . . . . . . . . . . 307

infinity, infinityf representation of infinity . . . . . . . . . . . . . . . 308

log1p, log1pf log of1 + x . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309

matherr modifiable math error handler . . . . . . . . . . . . . . . . . . . . . . 310

modf, modff split fractional and integer parts . . . . . . . . . . . . . . . . . 312

nan, nanf representation of Not a Number . . . . . . . . . . . . . . . . . . 313

nextafter, nextafterf get next number . . . . . . . . . . . . . . . . . . . 314

scalbn, scalbnf scale by power of two . . . . . . . . . . . . . . . . . . . . . 315

cbrtp, cbrtfp cube root . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316

copysignp, copysignfp sign ofy, magnitude ofx . . . . . . . . . . . . 317

expm1p, expm1fp exponential minus 1 . . . . . . . . . . . . . . . . . . . . . . 318

ilogbp, ilogbfp get exponent of floating-point number . . . . . . . . 319

infinityp,infinityfp

representation of infinity . . . . . . . . . . . . . 320

log1pp, log1pfp log of1 + x . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321

matherrp modifiable math error handler . . . . . . . . . . . . . . . . . . . . . 322

modfp, modffp split fractional and integer parts . . . . . . . . . . . . . . . 324

nanp, nanfp representation of Not a Number . . . . . . . . . . . . . . . . 325

nextafterp, nextafterfp get next number . . . . . . . . . . . . . . . . 326

scalbnp, scalbnfp scale by power of two . . . . . . . . . . . . . . . . . . . 327

acosh, acoshf inverse hyperbolic cosine . . . . . . . . . . . . . . . . . . . . 328

atanh, atanhf inverse hyperbolic tangent . . . . . . . . . . . . . . . . . . . 329hypot, hypotf distance from origin . . . . . . . . . . . . . . . . . . . . . . . . . 330

remainder, remainderf round and remainder . . . . . . . . . . . . . . 331

gamma, gammaf, lgamma, lgammaf, gamma_r, gammaf_r, lgamma_r,lgammaf_r logarithmic gamma function 332

acos, acosf arc cosine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333

asin, asinf, asine, asinef arc sine . . . . . . . . . . . . . . . . . . . . . . 334


12/605




asinh, asinhf inverse hyperbolic sine . . . . . . . . . . . . . . . . . . . . . . 335

atan2, atan2f arc tangent of y/x . . . . . . . . . . . . . . . . . . . . . . . . . . 336

atan, atanf arc tangent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337

cosh, coshf hyperbolic cosine . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338

erf, erff, erfc, erfcf error function . . . . . . . . . . . . . . . . . . . . . . 339

exp, expf exponential . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340

fabs, fabsf absolute value (magnitude) . . . . . . . . . . . . . . . . . . . . . 341

floor, floorf, ceil, ceilf floor and ceiling . . . . . . . . . . . . . . . . 342

fmod, fmodf floating-point remainder (modulo) . . . . . . . . . . . . . . . . 343

frexp, frexpf split floating-point number . . . . . . . . . . . . . . . . . . . . 344

isnan,isnanf,isinf,isinff,finite,finitef test for exceptional

numbers 345

ldexp, ldexpf load exponent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346

log10, log10f base 10 logarithms . . . . . . . . . . . . . . . . . . . . . . . . . 347

log, logf, logarithm, logarithmf natural logarithms . . . . . . . . 348

pow, powf x to the power y . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349

sin, cos, sine, sinf, cosf, sinef sine or cosine . . . . . . . . . . . . 350

sinh, sinhf, cosh, coshf, sineh hyperbolic sine or cosine . . . . 351

sqrt, sqrtf positive square root . . . . . . . . . . . . . . . . . . . . . . . . . . . 352

tan, tanf tangent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353

tanh, tanhf hyperbolic tangent . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354

acoshp, acoshfp inverse hyperbolic cosine . . . . . . . . . . . . . . . . . . 355

atanhp, atanhfp inverse hyperbolic tangent . . . . . . . . . . . . . . . . . 356

hypotp, hypotfp distance from origin . . . . . . . . . . . . . . . . . . . . . . 357

remainderp, remainderfp round and remainder . . . . . . . . . . . . 358

gammap, gammafp, lgammap, lgammafp, gammap_r, gammafp_r,lgammap_r, lgammafp_r logarithmic gamma function 359

acosp, acosfp arc cosine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360

asinp, asinfp, asinep, asinefp arc sine . . . . . . . . . . . . . . . . . . 361

asinhp, asinhfp inverse hyperbolic sine . . . . . . . . . . . . . . . . . . . . 362

atan2p, atan2fp arc tangent of y/x . . . . . . . . . . . . . . . . . . . . . . . . 363

atanp, atanfp arc tangent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364

coshp, coshfp hyperbolic cosine . . . . . . . . . . . . . . . . . . . . . . . . . . 365

erfp, erffp, erfcp, erfcfp error function . . . . . . . . . . . . . . . . . . 366


13/605




expp, expfp exponential . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367

fabsp, fabsfp absolute value (magnitude) . . . . . . . . . . . . . . . . . . . 368

floorp, floorfp, ceilp, ceilfp floor and ceiling . . . . . . . . . . . . 369

fmodp, fmodfp floating-point remainder (modulo) . . . . . . . . . . . . . . 370

frexpp, frexpfp poly split floating-point number . . . . . . . . . . . . . . 371

isnanp,isnanfp,isinfp,isinffp,finitep,finitefp poly test forexceptional numbers 372

ldexpp, ldexpfp poly load exponent . . . . . . . . . . . . . . . . . . . . . . . 373

log10p, log10fp poly base 10 logarithms . . . . . . . . . . . . . . . . . . . 374

logp, logfp poly natural logarithms . . . . . . . . . . . . . . . . . . . . . . . . 375

powp, powfp poly x to the power y . . . . . . . . . . . . . . . . . . . . . . . . . . 376

sinhp, sinhfp, coshp, coshfp, sinehp poly hyperbolic sine or cosine377

sinp, cosp, sinep, sinfp, cosfp, sinefp poly sine or cosine . . 378

sqrtp, sqrtfp poly positive square root . . . . . . . . . . . . . . . . . . . . . 379

tanhp, tanhfp poly hyperbolic tangent . . . . . . . . . . . . . . . . . . . . . . 380

tanp, tanfp poly tangent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381

2.2.1 Memory usage in math (mono) functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382

2.2.2 Memory usage in mathp (poly) functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386

3 Cn Extension Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395

3.1 Debug printing functions (dprint.h) . . . . . . . . . . . . . . . . . . . . . . . . . . 395

3.1.1 Formatting options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395

Style formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .395

Object formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .395

Calling dprint from assembly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .396

Note . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .396

Style formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .396

Object formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .396

3.1.2 Memory usage in dprint functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397

dprint_mono formatted print mono primitive . . . . . . . . . . . . . . . . . 398

dprint_mono_memory formatted print mono memory . . . . . . . . . . 399

dprint_mono_memory_raw print mono memory . . . . . . . . . . . . . . 400

dprint_poly formatted print poly primitive . . . . . . . . . . . . . . . . . . . 401

dprint_poly_memory formatted print poly memory . . . . . . . . . . . 402


14/605




dprint_poly_memory_pe formatted print poly memory on a single PE403

dprint_poly_memory_raw print poly memory . . . . . . . . . . . . . . . 404

dprint_poly_memory_pe_raw print poly memory on a single PE 405dprint_poly_pe formatted print poly primitive on a single PE . . . 406

vdprint formatted print of poly vector . . . . . . . . . . . . . . . . . . . . . . . 407

vdprint_pe formatted print of poly vector . . . . . . . . . . . . . . . . . . . . 408

3.2 Asynchronous memory transfer (async_string.h) . . . . . . . . . . . . . . 409

3.2.1 Alignment requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409

3.2.2 Scheduling transfers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409

3.2.3 Memory usage in async_string functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 410

async_memcpym2p copy from mono to poly memory . . . . . . . . . . 411async_memcpym2p_strided strided copy from mono to poly memory412

async_memcpyp2m copy from poly to mono memory . . . . . . . . . . 413

async_memcpyp2m_strided strided copy from poly to mono memory414

async_memcpym2p_inline copy from mono to poly memory . . . 415

async_memcpyp2m_inline copy from poly to mono memory . . . 417

async_memcpym2p_strided_inline strided copy from mono to

poly memory 419

async_memcpyp2m_strided_inline strided copy from poly tomono memory 421

async_memcpym2p_consolidated_inline consolidated copy frommono to poly memory 423

async_memcpyp2m_consolidated_inline consolidated copy frompoly to mono memory 425

pio_memcpym2p_addressed copy from mono to poly memory . . 427

pio_memcpym2p_addressed_sig copy from mono to poly memory

428pio_memcpym2p_addressed_offset copy from mono to polymemory 430

pio_memcpym2p_addressed_offset_sig copy from mono to polymemory 432

pio_memcpym2p_strided strided copy from mono to poly memory .434


15/605




pio_memcpym2p_strided_sig strided copy from mono to polymemory 436

pio_memcpym2p_strided_base_and_size -- strided copy from monoto poly memory 438

pio_memcpym2p_strided_base_and_size_sig strided copy frommono to poly memory 440

pio_memcpyp2m_addressed copy from poly to mono memory . . 442

pio_memcpyp2m_addressed_sig copy from poly to mono memory444

pio_memcpyp2m_addressed_offset copy from poly to monomemory 446

pio_memcpyp2m_addressed_offset_sig copy from poly to monomemory 448

pio_memcpyp2m_strided strided copy from poly to mono memory .450

pio_memcpyp2m_strided_sig strided copy from poly to monomemory 452

pio_memcpyp2m_strided strided copy from poly to mono memory .454

pio_memcpyp2m_strided_base_and_size_sig strided copy frompoly to mono memory 456

pio_set_addr_and_mask set the address and mask data for PIO . .

458

pio_set_strided_base set the strided base address for PIO . . 459

pio_get_strided_base get the strided base address for PIO . . 460

pio_set_strided_size set the strided size for PIO . . . . . . . . . 461

pio_get_strided_size get the strided size for PIO . . . . . . . . . 462

pio_set_data set the data for PIO . . . . . . . . . . . . . . . . . . . . . . . . 463

pio_set_data_sig get the data for PIO and signal . . . . . . . . . . 464

pio_get_data get the strided size for PIO . . . . . . . . . . . . . . . . . . 465

pio_get_data_sig get the strided size for PIO and signal . . . . . 466

pio_set_transfer_semaphore sets the PIO semaphore governingpoly writes to mono memory. 467

pio_get_transfer_semaphore gets the PIO semaphore governingpoly writes to mono memory. 468

pio_set_putget_semaphore sets the PIO semaphore governingwrites to PIO controller registers. 469


16/605




pio_get_putget_semaphore gets the PIO semaphore governingwrites to PIO controller registers. 470

pio_set_offset sets the PIO offset register. . . . . . . . . . . . . . . . 471

pio_get_offset gets the PIO offset value. . . . . . . . . . . . . . . . . . 472pio_update_strided_base updates the strided base address. 473

pio_issue_read Calls the PIO engine to issue a read operation 474

pio_issue_write Calls the PIO engine to issue a write operation . .475

pio_issue_strided_read Calls the PIO engine to issue a stridedread operation 476

pio_issue_strided_write Calls the PIO engine to issue a stridedwrite operation 477

pio_issue_consolidated_read Calls the PIO engine to issue aconsolidated read operation 478

pio_issue_consolidated_write Calls the PIO engine to issue aconsolidated write operation 479

pio_issue_write_sig Calls the PIO engine to issue a writeoperation and signals when completed. 480

pio_issue_strided_write_sig Calls the PIO engine to issue astrided write operation and signals when completed. 481

pio_issue_consolidated_write_sig Calls the PIO engine to

issue a consolidated write operation and signals when completed 482pio_atomic_start Starts an atomic sections and blocks waiting forPIO FIFO to be available 483

pio_atomic_end Endss an atomic sections . . . . . . . . . . . . . . . . . 484

pio_atomic_yield_start Starts an atomic sections and yieldswaiting for PIO FIFO to be available 485

3.3 Memory transfer (string_ext.h) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 486

3.3.1 Memory usage in string_ext functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 486

memcpym2p copy from mono to poly memory. . . . . . . . . . . . . . . . . . 487

memcpyp2m copy from poly to mono memory . . . . . . . . . . . . . . . . . . 488

3.4 PE to PE swazzle (swazzle.h) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489

3.4.1 Disabled PEs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490

3.4.2 Memory usage in swazzle functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490

circular_swazzle_down move data between PEs . . . . . . . . . . . 497

circular_swazzle_up move data between PEs . . . . . . . . . . . . . 498

get_swazzle_ends get swazzle path end values . . . . . . . . . . . . . 499


17/605




get_swazzle_high get swazzle path end value . . . . . . . . . . . . . . 500

get_swazzle_low get swazzle path end value . . . . . . . . . . . . . . . 501

set_swazzle_ends set swazzle-in values . . . . . . . . . . . . . . . . . . . 502

set_swazzle_high set swazzle-in high value . . . . . . . . . . . . . . . . 503

set_swazzle_low set swazzle-in low value . . . . . . . . . . . . . . . . . . 504

swazzle_down move data between PEs . . . . . . . . . . . . . . . . . . . . . 505

swazzle_down_max move data between PEs . . . . . . . . . . . . . . . . 506

swazzle_down_zero move data between PEs . . . . . . . . . . . . . . . 507

swazzle_up move data between PEs . . . . . . . . . . . . . . . . . . . . . . . 508

swazzle_up_max move data between PEs . . . . . . . . . . . . . . . . . . . 509

swazzle_up_zero move data between PEs . . . . . . . . . . . . . . . . . 510

3.5 On-chip DMA (dma.h) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .511

cs_initDCD initialize an on-chip DMA descriptor (DCD) . . . . . . . . 512

cs_invokeDMA invoke on-chip DMA transfer . . . . . . . . . . . . . . . . 514

cs_waitDMA wait on a given GSU semaphore . . . . . . . . . . . . . . . 515

3.6 Miscellaneous (misc.h) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 516

3.6.1 Memory usage in misc functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 517

any, all check for enabled PEs . . . . . . . . . . . . . . . . . . . . . . . . . . . 518

dcache_flush, dcache_flush_address data cache flushing

routines 519

get_penum, get_num_pes, get_cycles, get_cycles_ila getprocessor information 520

p2m_and_char, p2m_and_short, p2m_and_int, p2m_and_8byte poly to mono communication 521

sem_wait, sem_sig, sem_sync, sem_put, sem_get semaphorefunctions 522

4 The ClearSpeed Collectives Library . . . . . . . . . . . . . . . . . . . . . . . . . 523

4.1 Reduction operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 523

cs_reduce_sum sum reduction across the PEs . . . . . . . . . . . . . . 524

cs_reduce_prod product reduction across the PEs . . . . . . . . . . 525

cs_reduce_min find minimum across the PEs . . . . . . . . . . . . . . . 526

cs_reduce_max find maximum across the PEs . . . . . . . . . . . . . . 527

5 The ClearSpeed Vector Math Library . . . . . . . . . . . . . . . . . . . . . . . . . 529


18/605




5.1 Include files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529

5.2 Compilation and linking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529

5.3 Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529

5.4 Accuracy and error checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529

5.5 Memory management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529

cs_atanhp_init_data initializer function for explicit memorymanagement 532

cs_atanhp_init_data_sp initializer function for explicit memorymanagement 533

cs_atanp_init_data initializer function for explicit memorymanagement 534

cs_atanp_init_data_sp initializer function for explicit memory

management 535

cs_erfp_init_data initializer function for explicit memorymanagement 536

cs_expp_init_data initializer function for explicit memorymanagement 537

cs_expp_init_data_sp initializer function for explicit memorymanagement 538

cs_logp_init_data initializer function for explicit memorymanagement 539

cs_logp_init_data_sp initializer function for explicit memorymanagement 540

cs_powp_init_data initializer function for explicit memorymanagement 541

cs_sincosp_init_data initializer function for explicit memorymanagement 542

cs_sincosp_init_data_sp initializer function for explicit memorymanagement 543

cs_sqrtp_init_data initializer function for explicit memorymanagement 544

cs_sqrtp_init_data_sp initializer function for explicit memorymanagement 545

cs_tanp_init_data initializer function for explicit memorymanagement 546

cs_tanp_init_data_sp initializer function for explicit memorymanagement 547

5.6 Vector mathematical functions (vmathp.h) . . . . . . . . . . . . . . . . . . . . 548


19/605




cs_sinp poly sin/poly vector sin . . . . . . . . . . . . . . . . . . . . . . . . . . . 549

cs_cosp poly cosine/poly vector cosine . . . . . . . . . . . . . . . . . . . . . . 550

cs_sincosp poly sincos/poly vector sincos . . . . . . . . . . . . . . . . . . . 551

cs_tanp poly tangent/poly vector tangent . . . . . . . . . . . . . . . . . . . . 552

cs_tanhp poly hyperbolic tangent/poly vector hyperbolic tangent . . 553

cs_sqrtp poly positive square root/poly vector positive square root 554

cs_sinhp poly hyperbolic sin/poly vector hyperbolic sin . . . . . . . . . 555

cs_logp poly natural logarithm/poly vector natural logarithm . . . . . 556

cs_log10p poly base-10 logarithm/poly vector base-10 logarithm . 557

cs_isqrtp poly inverse square root/poly vector inverse square root . .558

cs_expp poly exponential/poly vector exponential . . . . . . . . . . . . . . 559

cs_coshp poly hyperbolic cosine/poly vector hyperbolic cosine . . . 560

cs_atanp poly arc tangent/poly vector arc tangent . . . . . . . . . . . . . 561

cs_atanhp poly inverse hyperbolic tangent/poly vector inversehyperbolic tangent 562

cs_fabsp poly vector absolute value (magnitude) . . . . . . . . . . . . . . 563

cs_fselp poly vector selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . 564

cs_minp poly vector min routine. . . . . . . . . . . . . . . . . . . . . . . . . . . . 565

cs_maxp poly vector max routine. . . . . . . . . . . . . . . . . . . . . . . . . . . 566cs_invp poly vector inverse. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 567

cs_divp poly vector divide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 568

cs_erfp poly erf/poly vector erf . . . . . . . . . . . . . . . . . . . . . . . . . . . . 569

cs_erfcp poly erfc/poly vector erfc . . . . . . . . . . . . . . . . . . . . . . . . . 570

cs_powp poly pow/poly vector pow . . . . . . . . . . . . . . . . . . . . . . . . . 571

cs_signp poly vector/scalar transfer sign . . . . . . . . . . . . . . . . . . . . 572

6 The ClearSpeed Random Number Generator Library . . . . . . . . . . . 5736.1 Streams (rngp.h) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 573

6.2 Compilation and Linking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 574

6.3 Initializations (rngp.h) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 574

6.4 Function calls and macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 574

6.4.1 Data-type macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 574

6.4.2 Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575


20/605




6.4.3 Random number generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575

6.5 Initialization Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 576

cs_init_rng_block_split RNG splitting initialization function . 577

cs_init_rng_leapfrog RNG leapfrog initialization function . . . . 578

cs_init_rng_multiseed RNG multiseed initialization function . . 579

cs_init_rng_dc_multiseed RNG dynamic creation initializationfunction 580

cs_mt2203_dyn_struct provide an mt_struct parameter fordynamic creation 581

6.6 Random number functions (rngp.h) . . . . . . . . . . . . . . . . . . . . . . . . . . 582

cs_rand48 pseudo-random number generator . . . . . . . . . . . . . . . 583

cs_mcg31m1 31-bit multiplicative congruential generator . . . . . . . . . 584cs_mcg59 59-bit multiplicative congruential generator . . . . . . . . . . . 585

cs_mt19937 pseudo-random number generator . . . . . . . . . . . . . . . 586

cs_mtN pseudo-random number generator . . . . . . . . . . . . . . . . . . . 587

6.7 Distributions (rngp.h) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 589

cs_gaussian distribution transformer . . . . . . . . . . . . . . . . . . . . . . . 590

cs_lognormal distribution transformer . . . . . . . . . . . . . . . . . . . . . . 591


21/605


Document No. 06-RM-1136 Revision: 3.00 21ClearSpeed Technology plc

1 ANSI C Library

This section documents the ANSI C library.

Copyright (C) 1992, 1993, 1994-2004 Red Hat, Inc.

libc includes software developed by the University of California, Berkeley and itscontributors.

libc includes software developed by Martin Jackson, Graham Haley and SteveChamberlain of Tadpole Technology and released to Cygnus.

libc uses floating-point conversion software developed at AT&T, which includes thiscopyright information:

The author of this software is David M. Gay.

Copyright (c) 1991 by AT&T.

Permission to use, copy, modify, and distribute this software for any purpose without fee ishereby granted, provided that this entire notice is included in all copies of any softwarewhich is or includes a copy or modification of this software and in all copies of the supportingdocumentation for such software.

THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR IMPLIEDWARRANTY. IN PARTICULAR, NEITHER THE AUTHOR NOR AT&T MAKES ANYREPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THEMERCHANTABILITY OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULARPURPOSE.

Permission is granted to make and distribute verbatim copies of this manual provided thecopyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under theconditions for verbatim copying, subject to the terms of the GNU General Public License,which includes the provision that the entire resulting derived work is distributed under theterms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into anotherlanguage, under the above conditions for modified versions.


22/605


22 Document No. 06-RM-1136 Revision: 3.00ClearSpeed Technology plc

1.1 Standard Utility Functions (stdlib.h, stdlibp.h)

This chapter groups utility functions useful in a variety of programs. The correspondingdeclarations are in the header files stdlib.h and stdlibp.h .


23/605



_Exit end program execution with no cleanup processing

Synopsis

#include void _Exit(int code);

Description

Use _Exit to return control from a program to the host operating environment. Use theargument code to pass an exit status to the operating environment: two particular values,EXIT_SUCCESS and EXIT_FAILURE, are defined in `stdlib.h' to indicate success orfailure in a portable fashion.

_Exit does not clean up files and streams. It is identical to _exit.

Returns

_Exit does not return to its caller.

Supporting OS subroutines required: _exit.


24/605



a64l,l64a convert between radix-64 ascii string and long

Synopsis

#include long a64l(const char *input);char *l64a(long input);

Description

Conversion is performed between long and radix-64 characters. The l64a routinetransforms up to 32-bits of input value starting from least significant bits to the mostsignificant bits. The input value is split up into a maximum of 5 groups of 6-bits and possiblyone group of 2 bits (bits 31 and 30).

Each group of 6 bits forms a value from 0-63 which is translated into a character as follows:

0 = '.' 1 = '/' 2-11 = '0' to '9' 12-37 = 'A' to 'Z' 38-63 = 'a' to 'z'

When remaining bits are zero or all bits have been translated, a nul terminator is appendedto the string. An input value of 0 results in the empty string.

The a64l performs the reverse translation. Each character is used to generate a 6-bitvalue for up to 30 bits and then a 2-bit value to complete a 32-bit result. The nul terminatormeans that the remaining digits are 0. An empty input string or NULL string results in 0L.

An invalid string results in undefined behavior. If the size of a long is > 32 bits, the result issign-extended.

Returns

l64a returns a nul-terminated string of 0 to 6 characters. a64l returns the 32-bit translatedvalue from the input character string.


25/605



abort abnormal termination of a program

Synopsis

#include void abort(void);

Description

Use abort to signal that your program has detected a condition it cannot deal with.Normally, abort ends your program's execution.

Returns

abort does not return to its caller.


26/605



abs integer absolute value (magnitude)

Synopsis

#include int abs(int i);

Description

abs returns the absolute value ofi (also called the magnitude ofi). That is, ifi isnegative, the result is the opposite ofi, but ifi is nonnegative the result is i.

The similar function labs uses and returns long rather than int values.

Returns

The result is a nonnegative integer.


27/605



assert Macro for Debugging Diagnostics

Synopsis

#include void assert(int expression);

Description

Use this macro to embed debuggging diagnostic statements in your programs. Theargument expression should be an expression which evaluates to true (nonzero) whenyour program is working as you intended.

When expression evaluates to false (zero), assert calls abort, after first printing amessage showing what failed and where:

Assertion failed: expression, file filename, line lineno

The macro is defined to permit you to turn off all uses ofassert at compile time by defining

NDEBUG as a preprocessor variable. If you do this, the assert macro expands to

(void(0))

Returns

assert does not return a value.


28/605



atof, atoff string to double or float

Synopsis

#include double atof(const char *s);float atoff(const char *s);

Description

atof converts the initial portion of a string to a double. atoff converts the initial portion ofa string to a float.

The functions parse the character string s, locating a substring which can be converted to afloating-point value. The substring must match the format: [+|-]digits[.][digits][(e|E)[+|-]digits] The substring converted is the longest initial fragment ofs that has the expectedformat, beginning with the first non-whitespace character. The substring is empty ifstr isempty, consists entirely of whitespace, or if the first non-whitespace character is something

other than +, -, ., or a digit.atof(s) is implemented as strtod(s, NULL). atoff(s) is implemented asstrtof(s, NULL).

Returns

atof returns the converted substring value, if any, as a double; or0.0, if no conversioncould be performed. If the correct value is out of the range of representable values, plus orminus HUGE_VAL is returned, and ERANGE is stored in errno. If the correct value wouldcause underflow, 0.0 is returned and ERANGE is stored in errno.

atoff obeys the same rules as atof, except that it returns a float.


29/605



atoi, atol string to integer

Synopsis

#include int atoi(const char *s);long atol(const char *s);int _atoi_r(struct _reent *ptr, const char *s);long _atol_r(struct _reent *ptr, const char *s);

Description

atoi converts the initial portion of a string to an int. atol converts the initial portion of astring to a long.

atoi(s) is implemented as (int)strtol(s, NULL, 10).atol(s) is implemented asstrtol(s, NULL, 10).

_atoi_r and _atol_r are reentrant versions ofatoi and atol respectively, passing the

reentrancy struct pointer.

Returns

The functions return the converted value, if any. If no conversion was made, 0 is returned.


30/605



calloc allocate space for arrays

Synopsis

#include void *calloc(size_t n, size_t s);

Description

Use calloc to request a block of memory sufficient to hold an array ofn elements, each ofwhich has size s.

The memory allocated by calloc comes out of the same memory pool used by malloc,but the memory block is initialized to all zero bytes. (To avoid the overhead of initializing thespace, use malloc instead.)

Returns

If successful, a pointer to the newly allocated space.

If unsuccessful, NULL.


31/605



div divide two integers

Synopsis

#include div_t div(int n, int d);

Description

Divide n/d, returning quotient and remainder as two integers in a structure div_t.

Returns

The result is represented with the structure

typedef struct { int quot; int rem; } div_t;

where the quot field represents the quotient, and rem the remainder. For nonzero d, if `r= div(n,d);' then n equals `r.rem + d*r.quot'.

To divide long rather than int values, use the similar function ldiv.


32/605



ecvtbuf, fcvtbuf double or float to string

Synopsis

#include char *ecvtbuf(double val, int chars, int *decpt,int *sgn, char *buf);char *fcvtbuf(double val, int decimals, int *decpt,int *sgn, char *buf);

Description

ecvtbuf and fcvtbuf produce (null-terminated) strings of digits representating thedouble numberval.

The only difference between ecvtbuf and fcvtbuf is the interpretation of the secondargument (chars ordecimals). Forecvtbuf, the second argument chars specifies thetotal number of characters to write (which is also the number of significant digits in theformatted string, since these two functions write only digits). Forfcvtbuf, the secondargument decimals specifies the number of characters to write after the decimal point; alldigits for the integer part ofval are always included.

Since ecvtbuf and fcvtbuf write only digits in the output string, they record the locationof the decimal point in *decpt, and the sign of the number in *sgn. After formatting anumber, *decpt contains the number of digits to the left of the decimal point. *sgncontains 0 if the number is positive, and 1 if it is negative. For both functions, you supply apointerbufto an area of memory to hold the converted string.

Returns

Both functions return a pointer to buf, the string containing a character representation ofval.


33/605



ecvt,ecvtf,fcvt,fcvtf double or float to string

Synopsis

#include char *ecvt(double val, int chars, int *decpt, int *sgn);char *ecvtf(float val, int chars, int *decpt, int *sgn);char *fcvt(double val, int decimals,int *decpt, int *sgn);char *fcvtf(float val, int decimals,int *decpt, int *sgn);

Description

ecvt and fcvt produce (null-terminated) strings of digits representating the doublenumberval. ecvtf and fcvtf produce the corresponding character representations offloat numbers.

(The stdlib functions ecvtbuf and fcvtbuf are reentrant versions ofecvt and fcvt.)

The only difference between ecvt and fcvt is the interpretation of the second argument(chars ordecimals). Forecvt, the second argument chars specifies the total number ofcharacters to write (which is also the number of significant digits in the formatted string,since these two functions write only digits). Forfcvt, the second argument decimalsspecifies the number of characters to write after the decimal point; all digits for the integerpart ofval are always included.

Since ecvt and fcvt write only digits in the output string, they record the location of thedecimal point in *decpt, and the sign of the number in *sgn. After formatting a number,*decpt contains the number of digits to the left of the decimal point. *sgn contains 0 if thenumber is positive, and 1 if it is negative.

Returns

All four functions return a pointer to the new string containing a character representation ofval.


34/605



gvcvt, gcvtf format double or float as string

Synopsis

#include char *gcvt(double val, int precision, char *buf);char *gcvtf(float val, int precision, char *buf);

Description

gcvt writes a fully formatted number as a null-terminated string in the buffer*buf. gdvtfproduces corresponding character representations offloat numbers.

gcvt uses the same rules as the printf format `%.precisiong' only negative valuesare signed (with `-'), and either exponential or ordinary decimal-fraction format is chosendepending on the number of significant digits (specified by precision).

Returns

The result is a pointer to the formatted representation ofval (the same as the argumentbuf).


35/605



exit end program execution

Synopsis

#include void exit(int code);

Description

Use exit to return control from a program to the host operating environment. Use theargument code to pass an exit status to the operating environment: two particular values,EXIT_SUCCESS and EXIT_FAILURE, are defined in `stdlib.h' to indicate success orfailure in a portable fashion.

Returns

exit does not return to its caller.

Supporting OS subroutines required: _exit.


36/605



labs long integer absolute value

Synopsis

#include long labs(long i);

Description

labs returns the absolute value ofi (also called the magnitude ofi). That is, ifi isnegative, the result is the opposite ofi, but ifi is nonnegative the result is i.

The similar function abs uses and returns int rather than long values.

Returns

The result is a nonnegative long integer.


37/605



ldiv divide two long integers

Synopsis

#include ldiv_t ldiv(long n, long d);

Description

Divide n/d, returning quotient and remainder as two long integers in a structure ldiv_t.

Returns

The result is represented with the structure

typedef struct { long quot; long rem; } ldiv_t;

where the quot field represents the quotient, and rem the remainder. For nonzero d, if `r= ldiv(n,d);' then n equals `r.rem + d*r.quot'.

To divide int rather than long values, use the similar function div.


38/605



malloc, realloc, free manage memory

Synopsis

#include void *malloc(size_t nbytes);void *realloc(void *aptr, size_t nbytes);void free(void *aptr);void *memalign(size_t align, size_t nbytes);size_t malloc_usable_size(void *aptr);

Description

These functions manage a pool of system memory.

Use malloc to request allocation of an object with at least nbytes bytes of storageavailable. If the space is available, malloc returns a pointer to a newly allocated block asits result.

If you already have a block of storage allocated by malloc, but you no longer need all thespace allocated to it, you can make it smaller by calling realloc with both the objectpointer and the new desired size as arguments. realloc guarantees that the contents ofthe smaller object match the beginning of the original object.

Similarly, if you need more space for an object, use realloc to request the larger size;again, realloc guarantees that the beginning of the new, larger object matches thecontents of the original object.

When you no longer need an object originally allocated by malloc orrealloc (or therelated function calloc), return it to the memory storage pool by calling free with theaddress of the object as the argument. You can also use realloc for this purpose bycalling it with 0 as the nbytes argument.

The memalign function returns a block of size nbytes aligned to a align boundary. Thealign argument must be a power of two.

The malloc_usable_size function takes a pointer to a block allocated by malloc. Itreturns the amount of space that is available in the block. This may or may not be morethan the size requested from malloc, due to alignment or minimum size constraints.

These functions operate by calling the function sbrk, which allocates space.

Returns

malloc returns a pointer to the newly allocated space, if successful; otherwise it returnsNULL. If your application needs to generate empty objects, you may use malloc(0) forthis purpose.

realloc returns a pointer to the new block of memory, orNULL if a new block could not beallocated. NULL is also the result when you use `realloc(aptr,0)' (which has the sameeffect as `free(aptr)'). You should always check the result ofrealloc; successfulreallocation is not guaranteed even when you request a smaller object.

free does not return a result.

memalign returns a pointer to the newly allocated space.

malloc_usable_size returns the usable size.


39/605



mblen minimal multibyte length function

Synopsis

#include int mblen(const char *s, size_t n);

Description

When _MB_CAPABLE is not defined, this is a minimal ANSI-conforming implementation ofmblen. In this case, the only multi-byte character sequences recognized are single bytes,and thus 1 is returned unless s is the null pointer or has a length of 0 or is the empty string.

When _MB_CAPABLE is defined, this routine calls _mbtowc_r to perform the conversion,passing a state variable to allow state dependent decoding. The result is based on thelocale setting which may be restricted to a defined set of locales.

Returns

This implementation ofmblen returns 0 ifs is NULL or the empty string; it returns 1 if not_MB_CAPABLE or the character is a single-byte character; it returns -1 if the multi-bytecharacter is invalid; otherwise it returns the number of bytes in the multibyte character.


40/605



_mblen_r reentrant minimal multibyte length function

Synopsis

#include int _mblen_r(struct _reent *r, const char *s, size_t n, int

*state);

Description

When _MB_CAPABLE is not defined, this is a minimal ANSI-conforming implementation of_mblen_r. In this case, the only multi-byte character sequences recognized are singlebytes, and thus 1 is returned unless s is the null pointer or has a length of 0 or is the emptystring.


Returns

This implementation of_mblen_r returns 0 ifs is NULL or the empty string; it returns 1 ifnot _MB_CAPABLE or the character is a single-byte character; it returns -1 if the multi-bytecharacter is invalid; otherwise it returns the number of bytes in the multibyte character.


41/605



mbstowcs minimal multibyte string to wide char converter

Synopsis

#include int mbstowcs(wchar_t *pwc, const char *s, size_t n);

Description

When _MB_CAPABLE is not defined, this is a minimal ANSI-conforming implementation ofmbstowcs. In this case, the only multi-byte character sequences recognized are singlebytes, and they are converted to wide-char versions simply by byte extension.

When _MB_CAPABLE is defined, this routine calls _mbstowcs_r to perform theconversion, passing a state variable to allow state dependent decoding. The result is basedon the locale setting which may be restricted to a defined set of locales.

Returns

This implementation ofmbstowcs returns 0 ifs is NULL or is the empty string; it returns -1if _MB_CAPABLE and one of the multi-byte characters is invalid or incomplete; otherwise itreturns the minimum of: n or the number of multi-byte characters in s plus 1 (to compensatefor the nul character). If the return value is -1, the state of the pwc string is indeterminate. Ifthe input has a length of 0, the output string will be modified to contain a wchar_t nulterminator.


42/605



mbtowc minimal multibyte to wide char converter

Synopsis

#include int mbtowc(wchar_t *pwc, const char *s, size_t n);

Description

When _MB_CAPABLE is not defined, this is a minimal ANSI-conforming implementation ofmbtowc. In this case, only multi-byte character sequences recognized are single bytes,and they are converted to themselves. Each call to mbtowc copies one character from *sto *pwc, unless s is a null pointer. The argument n is ignored.


ReturnsThis implementation ofmbtowc returns 0 ifs is NULL or is the empty string; it returns 1 if not

_MB_CAPABLE or the character is a single-byte character; it returns -1 if n is 0 or the multi-byte character is invalid; otherwise it returns the number of bytes in the multibyte character.If the return value is -1, no changes are made to the pwc output string. If the input is theempty string, a wchar_t nul is placed in the output string and 0 is returned. If the input has alength of 0, no changes are made to the pwc output string.


43/605



mallinfo, malloc_stats--malloc support

Synopsis

#include struct mallinfo mallinfo(void);void malloc_stats(void);

Description

mallinfo returns a structure describing the current state of memory allocation. Thestructure is defined in malloc.h. The following fields are defined: arena is the total amountof space in the heap; ordblks is the number of chunks which are not in use; uordblks isthe total amount of space allocated by malloc; fordblks is the total amount of space notin use; keepcost is the size of the top most memory block.

malloc_stats print some statistics about memory allocation to the screen.

Returns

mallinfo returns a mallinfo structure. The structure is defined in malloc.h.

malloc_stats does not return a result.


44/605



rand, srand pseudo-random numbers

Synopsis

#include int rand(void);void srand(unsigned int seed);int rand_r(unsigned int *seed);

Description

rand returns a different integer each time it is called; each integer is chosen by an algorithmdesigned to be unpredictable, so that you can use rand when you require a randomnumber. The algorithm depends on a static variable called the random seed; starting with agiven value of the random seed always produces the same sequence of numbers insuccessive calls to rand.

You can set the random seed using srand; it does nothing beyond storing its argument in

the static variable used by rand. You can exploit this to make the pseudo-randomsequence less predictable, if you wish, by using some other unpredictable value (often theleast significant parts of a time-varying value) as the random seed before beginning asequence of calls to rand; or, if you wish to ensure (for example, while debugging) thatsuccessive runs of your program use the same random numbers, you can use srand toset the same random seed at the outset.

Returns

rand returns the next pseudo-random integer in sequence; it is a number between 0 andRAND_MAX (inclusive).

srand does not return a result.

NOTES rand and srand are unsafe for multi-thread applications. rand_r is MT-Safe and

should be used instead.


45/605



rand48, drand48, erand48, lrand48, nrand48, mrand48, jrand48, srand48,seed48, lcong48 pseudo random number generators and initialization routines

Synopsis

#include double drand48(void);double erand48(unsigned short xseed[3]);long lrand48(void);long nrand48(unsigned short xseed[3]);long mrand48(void);long jrand48(unsigned short xseed[3]);void srand48(long seed);unsigned short *seed48(unsigned short xseed[3]);void lcong48(unsigned short p[7]);

Description

The rand48 family of functions generates pseudo-random numbers using a linear

congruential algorithm working on integers 48 bits in size. The particular formula employedis r(n+1) = (a * r(n) + c) mod m where the default values are for the multiplicand a =0xfdeece66d = 25214903917 and the addend c = 0xb = 11. The modulo is always fixed at m= 2 ** 48. r(n) is called the seed of the random number generator.

For all the six generator routines described next, the first computational step is to perform asingle iteration of the algorithm.

drand48 and erand48 return values of type double. The full 48 bits of r(n+1) are loadedinto the mantissa of the returned value, with the exponent set such that the values producedlie in the interval [0.0, 1.0].

lrand48 and nrand48 return values of type long in the range [0, 2**31-1]. The high-order(31) bits of r(n+1) are loaded into the lower bits of the returned value, with the topmost (sign)

bit set to zero.

mrand48 and jrand48 return values of type long in the range [-2**31, 2**31-1]. The high-order (32) bits of r(n+1) are loaded into the returned value.

drand48, lrand48, and mrand48 use an internal buffer to store r(n). For these functionsthe initial value of r(0) = 0x1234abcd330e = 20017429951246.

On the other hand, erand48, nrand48, and jrand48 use a user-supplied buffer to storethe seed r(n), which consists of an array of 3 shorts, where the zeroth member holds theleast significant bits.

All functions share the same multiplicand and addend.

srand48 is used to initialize the internal buffer r(n) ofdrand48, lrand48, and mrand48such that the 32 bits of the seed value are copied into the upper 32 bits of r(n), with thelower 16 bits of r(n) arbitrarily being set to 0x330e. Additionally, the constant multiplicandand addend of the algorithm are reset to the default values given above.

seed48 also initializes the internal buffer r(n) ofdrand48, lrand48, and mrand48, buthere all 48 bits of the seed can be specified in an array of 3 shorts, where the zerothmember specifies the lowest bits. Again, the constant multiplicand and addend of thealgorithm are reset to the default values given above. seed48 returns a pointer to an arrayof 3 shorts which contains the old seed. This array is statically allocated, thus its contentsare lost after each new call to seed48.


46/605



Finally, lcong48 allows full control over the multiplicand and addend used in drand48,erand48, lrand48, nrand48, mrand48, and jrand48, and the seed used in drand48,lrand48, and mrand48. An array of 7 shorts is passed as parameter; the first three shortsare used to initialize the seed; the second three are used to initialize the multiplicand; and

the last short is used to initialize the addend. It is thus not possible to use values greaterthan 0xffff as the addend.

Note that all three methods of seeding the random number generator always also set themultiplicand and addend for any of the six generator calls.


47/605



strtod, strtof string to double or float

Synopsis

#include double strtod(const char *str, char **tail);float strtof(const char *str, char **tail);double _strtod_r(void *reent,const char *str, char **tail);

Description

The function strtod parses the character string str, producing a substring which can beconverted to a double value. The substring converted is the longest initial subsequence ofstr, beginning with the first non-whitespace character, that has the format: .[+|-]digits[.][digits][(e|E)[+|-]digits] The substring contains no characters ifstris empty,consists entirely of whitespace, or if the first non-whitespace character is something otherthan +, -, ., or a digit. If the substring is empty, no conversion is done, and the value ofstr

is stored in *tail. Otherwise, the substring is converted, and a pointer to the final string(which will contain at least the terminating null character ofstr) is stored in *tail. If youwant no assignment to *tail, pass a null pointer as tail. strtof is identical to strtodexcept for its return type.

This implementation returns the nearest machine number to the input decimal string. Tiesare broken by using the IEEE round-even rule.

The alternate function _strtod_r is a reentrant version. The extra argument reent is apointer to a reentrancy structure.

Returns

strtod returns the converted substring value, if any. If no conversion could be performed,

0 is returned. If the correct value is out of the range of representable values, plus or minusHUGE_VAL is returned, and ERANGE is stored in errno. If the correct value would causeunderflow, 0 is returned and ERANGE is stored in errno.

Supporting OS subroutines required: close, fstat, isatty, lseek, read, sbrk, write.


48/605



strtol string to long

Synopsis

#include long strtol(const char *s, char **ptr,int base);long _strtol_r(void *reent,const char *s, char **ptr,int base);

Description

The function strtol converts the string *s to a long. First, it breaks down the string intothree parts: leading whitespace, which is ignored; a subject string consisting of charactersresembling an integer in the radix specified by base; and a trailing portion consisting of zeroor more unparseable characters, and always including the terminating null character. Then,it attempts to convert the subject string into a long and returns the result.

If the value ofbase is 0, the subject string is expected to look like a normal C integer

constant: an optional sign, a possible `0x' indicating a hexadecimal base, and a number. Ifbase is between 2 and 36, the expected form of the subject is a sequence of letters anddigits representing an integer in the radix specified by base, with an optional plus or minussign. The letters a--z (or, equivalently, A--Z) are used to signify values from 10 to 35; onlyletters whose ascribed values are less than base are permitted. Ifbase is 16, a leading 0xis permitted.

The subject sequence is the longest initial sequence of the input string that has theexpected form, starting with the first non-whitespace character. If the string is empty orconsists entirely of whitespace, or if the first non-whitespace character is not a permissibleletter or digit, the subject string is empty.

If the subject string is acceptable, and the value ofbase is zero, strtol attempts todetermine the radix from the input string. A string with a leading 0x is treated as a

hexadecimal value; a string with a leading 0 and no x is treated as octal; all other strings aretreated as decimal. Ifbase is between 2 and 36, it is used as the conversion radix, asdescribed above. If the subject string begins with a minus sign, the value is negated. Finally,a pointer to the first character past the converted subject string is stored in ptr, ifptris notNULL.

If the subject string is empty (or not in acceptable form), no conversion is performed and thevalue ofs is stored in ptr(ifptris not NULL).

The alternate function _strtol_r is a reentrant version. The extra argument reent is apointer to a reentrancy structure.

Returns

strtol returns the converted value, if any. If no conversion was made, 0 is returned.

strtol returns LONG_MAX orLONG_MIN if the magnitude of the converted value is toolarge, and sets errno to ERANGE.


49/605



strtoul string to unsigned long

Synopsis

#include unsigned long strtoul(const char *s, char **ptr,int base);unsigned long _strtoul_r(void *reent, const char *s,char **ptr, int base);

Description

The function strtoul converts the string *s to an unsigned long. First, it breaks downthe string into three parts: leading whitespace, which is ignored; a subject string consistingof the digits meaningful in the radix specified by base (for example, 0 through 7 if the valueofbase is 8); and a trailing portion consisting of one or more unparseable characters, whichalways includes the terminating null character. Then, it attempts to convert the subject stringinto an unsigned long integer, and returns the result.

If the value ofbase is zero, the subject string is expected to look like a normal C integerconstant (save that no optional sign is permitted): a possible 0x indicating hexadecimalradix, and a number. Ifbase is between 2 and 36, the expected form of the subject is asequence of digits (which may include letters, depending on the base) representing aninteger in the radix specified by base. The letters a--z (orA--Z) are used as digits valuedfrom 10 to 35. Ifbase is 16, a leading 0x is permitted.

The subject sequence is the longest initial sequence of the input string that has theexpected form, starting with the first non-whitesp

Documents

Cn Standard Library Reference Manual 3.1 Rev3.A