AD-CCES-MNT-N1 - Analog Devices

1.1

C/C++ Library Manual

for SHARC® Processors

Revision 1.2, May 2014

Part Number

82-100118-01

Analog Devices, Inc.

One Technology Way

Norwood, Mass. 02062-9106

may not be reproduced in any form without prior, express written consent

from Analog Devices, Inc.

Printed in the USA.

Disclaimer

Analog Devices, Inc. reserves the right to change this product without

prior notice. Information furnished by Analog Devices is believed to be

accurate and reliable. However, no responsibility is assumed by Analog

Devices for its use; nor for any infringement of patents or other rights of

third parties which may result from its use. No license is granted by impli-

cation or otherwise under the patent rights of Analog Devices, Inc.

Trademark and Service Mark Notice

The Analog Devices logo, CrossCore, EngineerZone, EZ-KIT Lite,

SHARC, and VisualDSP++ are registered trademarks of Analog Devices,

Inc.

All other brand and product names are trademarks or service marks of

their respective owners.

CrossCore Embedded Studio 1.1 iii

C/C++ Library Manual for SHARC Processors

CONTENTS

PREFACE

Purpose of This Manual ............................................................ xxiii

Intended Audience .................................................................... xxiii

Manual Contents ....................................................................... xxiv

What’s New in This Manual ....................................................... xxiv

Technical Support ....................................................................... xxv

Supported Processors .................................................................. xxvi

Product Information .................................................................. xxvi

Analog Devices Web Site ..................................................... xxvii

EngineerZone ...................................................................... xxvii

Notation Conventions .............................................................. xxviii

C/C++ RUN-TIME LIBRARY

C and C++ Run-Time Libraries Guide ........................................... 1-2

Calling Library Functions ........................................................ 1-3

Linking Library Functions ....................................................... 1-3

Functional Breakdown ........................................................ 1-4

Library Location ................................................................. 1-5

Library Selection ................................................................. 1-6

Contents

iv CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

Library Naming .................................................................. 1-6

Library Startup Files ........................................................... 1-8

Library Attributes ................................................................... 1-8

Exceptions to the Attribute Conventions ........................... 1-12

Mapping Objects to FLASH Memory Using Attributes ...... 1-13

Working With Library Header Files ....................................... 1-13

adi_types.h ....................................................................... 1-15

assert.h ............................................................................. 1-15

ctype.h ............................................................................. 1-16

cycle_count.h ................................................................... 1-16

cycles.h ............................................................................ 1-17

errno.h ............................................................................. 1-17

float.h .............................................................................. 1-17

heap_debug.h ................................................................... 1-18

instrprof.h ........................................................................ 1-21

iso646.h ........................................................................... 1-21

libdyn.h ........................................................................... 1-21

limits.h ............................................................................ 1-22

locale.h ............................................................................ 1-22

math.h ............................................................................. 1-22

misra_types.h ................................................................... 1-24

pgo_hw.h ......................................................................... 1-24

setjmp.h ........................................................................... 1-24

signal.h ............................................................................ 1-24

CrossCore Embedded Studio 1.1 v

C/C++ Library Manual for SHARC Processors

Contents

stdarg.h ............................................................................ 1-24

stdbool.h .......................................................................... 1-25

stddef.h ............................................................................ 1-25

stdfix.h ............................................................................. 1-25

stdint.h ............................................................................. 1-25

stdio.h .............................................................................. 1-27

stdlib.h ............................................................................. 1-29

string.h ............................................................................. 1-31

time.h ............................................................................... 1-31

Calling Library Functions From an ISR .................................. 1-33

Using the Libraries in a Multi-Threaded Environment ............ 1-34

Using Compiler Built-In C Library Functions ........................ 1-35

Abridged C++ Library Support .............................................. 1-36

Embedded C++ Library Header Files ................................. 1-37

complex ........................................................................ 1-37

exception ...................................................................... 1-37

fstream .......................................................................... 1-38

iomanip ........................................................................ 1-38

ios ................................................................................ 1-38

iosfwd ........................................................................... 1-38

iostream ........................................................................ 1-38

istream .......................................................................... 1-38

new .............................................................................. 1-38

ostream ......................................................................... 1-38

Contents

vi CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

sstream ......................................................................... 1-39

stdexcept ...................................................................... 1-39

streambuf ..................................................................... 1-39

string ............................................................................ 1-39

strstream ...................................................................... 1-39

C++ Header Files for C Library Facilities ........................... 1-40

Embedded Standard Template Library Header Files ........... 1-41

algorithm ..................................................................... 1-41

deque ........................................................................... 1-41

functional ..................................................................... 1-41

hash_map ..................................................................... 1-41

hash_set ....................................................................... 1-41

iterator ......................................................................... 1-41

list ................................................................................ 1-42

map .............................................................................. 1-42

memory ........................................................................ 1-42

numeric ........................................................................ 1-42

queue ........................................................................... 1-42

set ................................................................................ 1-42

stack ............................................................................ 1-42

utility ........................................................................... 1-42

vector ........................................................................... 1-42

Header Files for C++ Library Compatibility ...................... 1-43

CrossCore Embedded Studio 1.1 vii

C/C++ Library Manual for SHARC Processors

Contents

Measuring Cycle Counts ........................................................ 1-43

Basic Cycle Counting Facility ............................................ 1-44

Cycle Counting Facility With Statistics .............................. 1-46

Using time.h to Measure Cycle Counts .............................. 1-49

Determining the Processor Clock Rate ............................... 1-50

Considerations When Measuring Cycle Counts .................. 1-51

File I/O Support .................................................................... 1-53

Fatal Error Handling ............................................................. 1-54

FatalError.xml ................................................................... 1-55

General Codes .................................................................. 1-55

Library Error Specific Codes .............................................. 1-56

Errno Values ..................................................................... 1-58

Documented Library Functions ................................................... 1-58

C Run-Time Library Reference .................................................... 1-65

abort .......................................................................................... 1-66

abs .............................................................................................. 1-67

absfx ........................................................................................... 1-68

acos ............................................................................................ 1-69

adi_dump_all_heaps ................................................................... 1-70

adi_dump_heap .......................................................................... 1-72

adi_fatal_error ............................................................................ 1-74

adi_fatal_exception ..................................................................... 1-76

adi_heap_debug_disable .............................................................. 1-78

adi_heap_debug_enable .............................................................. 1-80

Contents

viii CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

adi_heap_debug_end .................................................................. 1-82

adi_heap_debug_flush ................................................................ 1-84

adi_heap_debug_pause ............................................................... 1-86

adi_heap_debug_reset_guard_region ........................................... 1-88

adi_heap_debug_resume ............................................................. 1-90

adi_heap_debug_set_buffer ........................................................ 1-92

adi_heap_debug_set_call_stack_depth ........................................ 1-94

adi_heap_debug_set_error .......................................................... 1-96

adi_heap_debug_set_guard_region .............................................. 1-98

adi_heap_debug_set_ignore ...................................................... 1-101

adi_heap_debug_set_warning ................................................... 1-103

adi_verify_all_heaps ................................................................. 1-105

adi_verify_heap ........................................................................ 1-107

asctime ..................................................................................... 1-109

asin .......................................................................................... 1-111

atan .......................................................................................... 1-112

atan2 ........................................................................................ 1-113

atexit ....................................................................................... 1-114

atof .......................................................................................... 1-115

atoi .......................................................................................... 1-118

atol .......................................................................................... 1-119

atold ........................................................................................ 1-120

atoll ......................................................................................... 1-123

avg ........................................................................................... 1-124

CrossCore Embedded Studio 1.1 ix

C/C++ Library Manual for SHARC Processors

Contents

bitsfx ........................................................................................ 1-125

bsearch ..................................................................................... 1-126

calloc ........................................................................................ 1-129

ceil ........................................................................................... 1-131

clearerr ..................................................................................... 1-132

clip ........................................................................................... 1-134

clock ......................................................................................... 1-135

cos ............................................................................................ 1-137

cosh .......................................................................................... 1-138

count_ones ............................................................................... 1-139

countlsfx ................................................................................... 1-140

ctime ........................................................................................ 1-142

difftime .................................................................................... 1-144

div ............................................................................................ 1-146

divifx ........................................................................................ 1-148

dyn_AddHeap ........................................................................... 1-149

dyn_alloc .................................................................................. 1-151

dyn_AllocSectionMem .............................................................. 1-153

dyn_AllocSectionMemHeap ...................................................... 1-156

dyn_CopySectionContents ........................................................ 1-159

dyn_FreeEntryPointArray .......................................................... 1-161

dyn_FreeSectionMem ................................................................ 1-162

dyn_GetEntryPointArray .......................................................... 1-164

dyn_GetExpSymTab ................................................................. 1-167

Contents

x CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

dyn_GetHeapForWidth ............................................................ 1-169

dyn_GetNumSections ............................................................... 1-171

dyn_GetSections ...................................................................... 1-173

dyn_GetStringTable .................................................................. 1-175

dyn_GetStringTableSize ............................................................ 1-177

dyn_heap_init .......................................................................... 1-179

dyn_LookupByName ................................................................ 1-181

dyn_RecordRelocOutOfRange .................................................. 1-184

dyn_Relocate ............................................................................ 1-186

dyn_RetrieveRelocOutOfRange ................................................ 1-188

dyn_RewriteImageToFile .......................................................... 1-190

dyn_SetSectionAddr ................................................................. 1-192

dyn_SetSectionMem ................................................................. 1-194

dyn_ValidateImage ................................................................... 1-196

exit ........................................................................................... 1-198

exp ........................................................................................... 1-199

fabs .......................................................................................... 1-200

fclose ........................................................................................ 1-201

feof .......................................................................................... 1-203

ferror ........................................................................................ 1-204

fflush ....................................................................................... 1-205

fgetc ......................................................................................... 1-206

fgetpos ..................................................................................... 1-208

fgets ......................................................................................... 1-210

CrossCore Embedded Studio 1.1 xi

C/C++ Library Manual for SHARC Processors

Contents

fileno ........................................................................................ 1-212

floor ......................................................................................... 1-213

fmod ........................................................................................ 1-214

fopen ........................................................................................ 1-215

fprintf ....................................................................................... 1-217

fputc ......................................................................................... 1-223

fputs ......................................................................................... 1-224

fread ......................................................................................... 1-225

free ........................................................................................... 1-227

freopen ..................................................................................... 1-228

frexp ......................................................................................... 1-230

fscanf ........................................................................................ 1-232

fseek ......................................................................................... 1-237

fsetpos ...................................................................................... 1-239

ftell ........................................................................................... 1-240

fwrite ........................................................................................ 1-242

fxbits ........................................................................................ 1-244

fxdivi ........................................................................................ 1-245

getc .......................................................................................... 1-246

getchar ...................................................................................... 1-248

getenv ....................................................................................... 1-250

gets ........................................................................................... 1-251

gmtime ..................................................................................... 1-253

heap_calloc ............................................................................... 1-255

Contents

xii CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

heap_free .................................................................................. 1-257

heap_init .................................................................................. 1-259

heap_install .............................................................................. 1-261

heap_lookup ............................................................................ 1-263

heap_malloc ............................................................................. 1-265

heap_realloc ............................................................................. 1-267

heap_space_unused .................................................................. 1-270

heap_switch ............................................................................. 1-272

idivfx ....................................................................................... 1-274

instrprof_request_flush ............................................................. 1-275

ioctl ......................................................................................... 1-277

isalnum .................................................................................... 1-278

isalpha ...................................................................................... 1-279

iscntrl ....................................................................................... 1-280

isdigit ....................................................................................... 1-281

isgraph ..................................................................................... 1-282

isinf ......................................................................................... 1-283

islower ...................................................................................... 1-285

isnan ........................................................................................ 1-286

isprint ...................................................................................... 1-288

ispunct ..................................................................................... 1-289

isspace ...................................................................................... 1-290

isupper ..................................................................................... 1-292

isxdigit ..................................................................................... 1-293

CrossCore Embedded Studio 1.1 xiii

C/C++ Library Manual for SHARC Processors

Contents

labs ........................................................................................... 1-294

lavg .......................................................................................... 1-295

lclip .......................................................................................... 1-296

lcount_ones .............................................................................. 1-297

ldexp ........................................................................................ 1-298

ldiv ........................................................................................... 1-299

llabs .......................................................................................... 1-301

llavg ......................................................................................... 1-302

llclip ......................................................................................... 1-303

llcount_ones ............................................................................. 1-304

lldiv .......................................................................................... 1-305

llmax ........................................................................................ 1-307

llmin ........................................................................................ 1-308

lmax ......................................................................................... 1-309

lmin ......................................................................................... 1-310

localeconv ................................................................................. 1-311

localtime ................................................................................... 1-314

log ............................................................................................ 1-316

log10 ........................................................................................ 1-317

longjmp .................................................................................... 1-318

malloc ...................................................................................... 1-320

max .......................................................................................... 1-321

memchr .................................................................................... 1-322

memcmp .................................................................................. 1-323

Contents

xiv CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

memcpy ................................................................................... 1-324

memmove ................................................................................ 1-325

memset .................................................................................... 1-326

min .......................................................................................... 1-327

mktime .................................................................................... 1-328

modf ........................................................................................ 1-331

mulifx ...................................................................................... 1-332

perror ....................................................................................... 1-333

pgo_hw_request_flush .............................................................. 1-335

pow .......................................................................................... 1-337

printf ....................................................................................... 1-338

putc ......................................................................................... 1-340

putchar .................................................................................... 1-341

puts .......................................................................................... 1-342

qsort ........................................................................................ 1-343

raise ......................................................................................... 1-345

rand ......................................................................................... 1-346

read_extmem ............................................................................ 1-347

realloc ...................................................................................... 1-349

remove ..................................................................................... 1-351

rename ..................................................................................... 1-352

rewind ...................................................................................... 1-354

roundfx .................................................................................... 1-356

scanf ........................................................................................ 1-358

CrossCore Embedded Studio 1.1 xv

C/C++ Library Manual for SHARC Processors

Contents

setbuf ....................................................................................... 1-360

setjmp ...................................................................................... 1-362

setlocale .................................................................................... 1-364

setvbuf ...................................................................................... 1-365

signal ........................................................................................ 1-367

sin ............................................................................................ 1-369

sinh .......................................................................................... 1-370

snprintf .................................................................................... 1-371

space_unused ............................................................................ 1-373

sprintf ...................................................................................... 1-374

sqrt ........................................................................................... 1-376

srand ........................................................................................ 1-377

sscanf ........................................................................................ 1-378

strcat ........................................................................................ 1-380

strchr ........................................................................................ 1-381

strcmp ...................................................................................... 1-382

strcoll ....................................................................................... 1-383

strcpy ....................................................................................... 1-384

strcspn ...................................................................................... 1-385

strerror ..................................................................................... 1-386

strftime ..................................................................................... 1-387

strlen ........................................................................................ 1-391

strncat ...................................................................................... 1-392

strncmp .................................................................................... 1-393

Contents

xvi CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

strncpy ..................................................................................... 1-394

strpbrk ..................................................................................... 1-395

strrchr ...................................................................................... 1-396

strspn ....................................................................................... 1-397

strstr ........................................................................................ 1-398

strtod ....................................................................................... 1-399

strtofxfx ................................................................................... 1-402

strtok ....................................................................................... 1-405

strtol ........................................................................................ 1-407

strtold ...................................................................................... 1-409

strtoll ....................................................................................... 1-412

strtoul ...................................................................................... 1-414

strtoull ..................................................................................... 1-416

strxfrm ..................................................................................... 1-418

system ...................................................................................... 1-420

tan ........................................................................................... 1-421

tanh ......................................................................................... 1-422

time ......................................................................................... 1-423

tolower ..................................................................................... 1-424

toupper .................................................................................... 1-425

ungetc ...................................................................................... 1-426

va_arg ...................................................................................... 1-428

va_end ..................................................................................... 1-431

va_start .................................................................................... 1-432

CrossCore Embedded Studio 1.1 xvii

C/C++ Library Manual for SHARC Processors

Contents

vfprintf ..................................................................................... 1-433

vprintf ...................................................................................... 1-435

vsnprintf ................................................................................... 1-437

vsprintf ..................................................................................... 1-439

write_extmem ........................................................................... 1-441

DSP RUN-TIME LIBRARY

DSP Run-Time Library Guide ....................................................... 2-2

Calling DSP Library Functions ................................................ 2-2

Reentrancy .............................................................................. 2-3

Library Attributes .................................................................... 2-3

Working With Library Source Code ......................................... 2-3

DSP Header Files .................................................................... 2-4

asm_sprt.h .......................................................................... 2-5

cmatrix.h ............................................................................ 2-5

comm.h .............................................................................. 2-5

complex.h ........................................................................... 2-6

cvector.h ............................................................................. 2-7

filter.h ................................................................................ 2-7

filters.h ............................................................................... 2-9

macros.h ............................................................................. 2-9

math.h ................................................................................ 2-9

matrix.h ............................................................................ 2-11

platform_include.h ........................................................... 2-11

Contents

xviii CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

Header Files That Define Processor-Specific System

Header Files That Allow Access to Memory-Mapped

Registers From C/C++ Code ...................................... 2-13

stats.h .............................................................................. 2-14

sysreg.h ............................................................................ 2-14

trans.h .............................................................................. 2-14

vector.h ............................................................................ 2-15

window.h ......................................................................... 2-15

Built-In DSP Library Functions ............................................ 2-16

Implications of Using SIMD Mode ....................................... 2-17

Using Data in External Memory ............................................ 2-19

Documented Library Functions .................................................. 2-20

DSP Run-Time Library Reference ............................................... 2-24

a_compress ................................................................................. 2-25

a_expand .................................................................................... 2-27

alog ............................................................................................ 2-29

alog10 ........................................................................................ 2-30

arg ............................................................................................. 2-31

autocoh ...................................................................................... 2-33

autocorr ..................................................................................... 2-35

biquad ........................................................................................ 2-37

cabs ............................................................................................ 2-42

cadd ........................................................................................... 2-44

cartesian ..................................................................................... 2-45

CrossCore Embedded Studio 1.1 xix

C/C++ Library Manual for SHARC Processors

Contents

cdiv ............................................................................................ 2-47

cexp ............................................................................................ 2-49

cfft ............................................................................................. 2-51

cfft_mag ..................................................................................... 2-54

cfftN .......................................................................................... 2-56

cfftN .......................................................................................... 2-60

cfftf ............................................................................................ 2-63

cmatmadd ................................................................................... 2-66

cmatmmlt ................................................................................... 2-68

cmatmsub ................................................................................... 2-71

cmatsadd .................................................................................... 2-73

cmatsmlt ..................................................................................... 2-75

cmatssub ..................................................................................... 2-77

cmlt ............................................................................................ 2-79

conj ............................................................................................ 2-80

convolve ..................................................................................... 2-81

copysign ..................................................................................... 2-83

cot .............................................................................................. 2-84

crosscoh ...................................................................................... 2-86

crosscorr ..................................................................................... 2-89

csub ............................................................................................ 2-92

cvecdot ....................................................................................... 2-93

cvecsadd ..................................................................................... 2-95

cvecsmlt ...................................................................................... 2-97

Contents

xx CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

cvecssub ..................................................................................... 2-99

cvecvadd ................................................................................... 2-101

cvecvmlt ................................................................................... 2-103

cvecvsub ................................................................................... 2-105

favg .......................................................................................... 2-107

fclip ......................................................................................... 2-108

fft_magnitude ........................................................................... 2-109

fftf_magnitude ......................................................................... 2-113

fir ............................................................................................ 2-116

fir_decima ................................................................................ 2-120

fir_interp .................................................................................. 2-123

firf ........................................................................................... 2-128

fmax ......................................................................................... 2-132

fmin ......................................................................................... 2-133

gen_bartlett .............................................................................. 2-134

gen_blackman .......................................................................... 2-136

gen_gaussian ............................................................................ 2-138

gen_hamming .......................................................................... 2-140

gen_hanning ............................................................................ 2-142

gen_harris ................................................................................ 2-144

gen_kaiser ................................................................................ 2-146

gen_rectangular ........................................................................ 2-148

gen_triangle ............................................................................. 2-150

gen_vonhann ............................................................................ 2-152

CrossCore Embedded Studio 1.1 xxi

C/C++ Library Manual for SHARC Processors

Contents

histogram ................................................................................. 2-153

ifft ............................................................................................ 2-155

ifftf ........................................................................................... 2-158

ifftN ......................................................................................... 2-161

ifftN ......................................................................................... 2-165

iir ............................................................................................. 2-168

matinv ...................................................................................... 2-176

matmadd .................................................................................. 2-178

matmmlt .................................................................................. 2-180

matmsub .................................................................................. 2-182

matsadd .................................................................................... 2-184

matsmlt .................................................................................... 2-186

matssub .................................................................................... 2-188

mean ........................................................................................ 2-190

mu_compress ............................................................................ 2-191

mu_expand ............................................................................... 2-193

norm ........................................................................................ 2-195

polar ......................................................................................... 2-197

rfft ............................................................................................ 2-199

rfft_mag ................................................................................... 2-203

rfftf_2 ....................................................................................... 2-205

rfftN ......................................................................................... 2-208

rfftN ......................................................................................... 2-211

rms ........................................................................................... 2-215

Contents

xxii CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

rsqrt ......................................................................................... 2-217

transpm .................................................................................... 2-218

twidfft ...................................................................................... 2-220

twidfftf ..................................................................................... 2-223

var ........................................................................................... 2-226

vecdot ...................................................................................... 2-228

vecsadd .................................................................................... 2-230

vecsmlt ..................................................................................... 2-232

vecssub ..................................................................................... 2-234

vecvadd .................................................................................... 2-236

vecvmlt .................................................................................... 2-238

vecvsub .................................................................................... 2-240

zero_cross ................................................................................. 2-242

INDEX

CrossCore Embedded Studio 1.1 xxiii

C/C++ Library Manual for SHARC Processors

PREFACE

Thank you for purchasing Analog Devices, Inc. development software for

signal processing applications.

Purpose of This Manual

The C/C++ Library Manual contains information about the C/C++ and

DSP run-time libraries for SHARC® (ADSP-21xxx) processors. It leads

you through the process of using library routines and provides informa-

tion about the ANSI standard header files and different libraries that are

included with this release of the cc21k compiler.

Intended Audience

The primary audience for this manual is a programmer who is familiar

with Analog Devices processors. This manual assumes that the audience

has a working knowledge of the SHARC architecture and the C/C++ pro-

gramming languages.

Programmers who are unfamiliar with SHARC processors can use this

manual, but they should supplement it with other texts (such as the

appropriate hardware reference and programming reference manuals) that

describe their target architecture.

Manual Contents

xxiv CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

Manual Contents

This manual contains:

• Chapter 1, C/C++ Run-Time Library

Describes how to use library functions and provides a complete

C/C++ library function reference (for functions covered in the cur-

rent compiler release)

• Chapter 2, DSP Run-Time Library

Describes how to use DSP library functions and provides a com-

plete library function reference (for functions covered in the

current compiler release)

What’s New in This Manual

This is Revision 1.2 of the C/C++ Library Manual. It documents C/C++

and DSP libraries for all current SHARC processors listed in the Cross-

Core® Embedded Studio (CCES) online help.

This revision corrects typographical errors and resolves document errata

reported against the previous revision.

CrossCore Embedded Studio 1.1 xxv

C/C++ Library Manual for SHARC Processors

Preface

Technical Support

You can reach Analog Devices processors and DSP technical support in

the following ways:

• Post your questions in the processors and DSP support community

at EngineerZone®:

http://ez.analog.com/community/dsp

• Submit your questions to technical support directly at:

http://www.analog.com/support

• E-mail your questions about processors, DSPs, and tools develop-

ment software from CrossCore Embedded Studio or

VisualDSP++®:

Choose Help > Email Support. This creates an e-mail to

processor.tools.support@analog.com and automatically attaches

your CrossCore Embedded Studio or VisualDSP++ version infor-

mation and license.dat file.

• E-mail your questions about processors and processor applications

to:

processor.support@analog.com or

processor.china@analog.com (Greater China support)

• Contact your Analog Devices sales office or authorized distributor.

Locate one at:

www.analog.com/adi-sales

• Send questions by mail to:

Processors and DSP Technical Support

Analog Devices, Inc.

Three Technology Way

P.O. Box 9106

Norwood, MA 02062-9106

USA

Supported Processors

xxvi CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

Supported Processors

The name “SHARC” refers to a family of Analog Devices, Inc.

high-performance 32-bit floating-point digital signal processors that can

be used in speech, sound, graphics, and imaging applications. Refer to the

CCES online help for a complete list of supported processors.

Product Information

Product information can be obtained from the Analog Devices Web site

and the CCES online help.

Analog Devices Web Site

The Analog Devices Web site, www.analog.com, provides information

about a broad range of products—analog integrated circuits, amplifiers,

converters, and digital signal processors.

To access a complete technical library for each processor family, go to

http://www.analog.com/processors/technical_library. The manuals

selection opens a list of current manuals related to the product as well as a

link to the previous revisions of the manuals. When locating your manual

title, note a possible errata check mark next to the title that leads to the

current correction report against the manual.

Also note, myAnalog is a free feature of the Analog Devices Web site that

allows customization of a Web page to display only the latest information

about products you are interested in. You can choose to receive weekly

e-mail notifications containing updates to the Web pages that meet your

interests, including documentation errata against all manuals. myAnalog

CrossCore Embedded Studio 1.1 xxvii

C/C++ Library Manual for SHARC Processors

Preface

provides access to books, application notes, data sheets, code examples,

and more.

Visit myAnalog to sign up. If you are a registered user, just log on. Your

user name is your e-mail address.

EngineerZone

EngineerZone is a technical support forum from Analog Devices. It allows

you direct access to ADI technical support engineers. You can search

FAQs and technical information to get quick answers to your embedded

processing and DSP design questions.

Use EngineerZone to connect with other DSP developers who face similar

design challenges. You can also use this open forum to share knowledge

and collaborate with the ADI support team and your peers. Visit

http://ez.analog.com to sign up.

Notation Conventions

Text conventions used in this manual are identified and described as

follows.

Example Description

File > Close Titles in bold style reference sections indicate the location of an item

within the CrossCore Embedded Studio’s menu system (for example,

the Close command appears on the File menu).

{this | that} Alternative required items in syntax descriptions appear within curly

brackets and separated by vertical bars; read the example as this or

that. One or the other is required.

[this | that] Optional items in syntax descriptions appear within brackets and sepa-

rated by vertical bars; read the example as an optional this or that.

Notation Conventions

xxviii CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

[this,…] Optional item lists in syntax descriptions appear within brackets delim-

ited by commas and terminated with an ellipsis; read the example as an

optional comma-separated list of this.

.SECTION Commands, directives, keywords, and feature names are in text with

letter gothic font.

filename Non-keyword placeholders appear in text with italic style format.

Note: For correct operation, ...

A Note provides supplementary information on a related topic. In the

online version of this book, the word Note appears instead of this

symbol.

Caution: Incorrect device operation may result if ...

Caution: Device damage may result if ...

A Caution identifies conditions or inappropriate usage of the product

that could lead to undesirable results or product damage. In the online

version of this book, the word Caution appears instead of this symbol.

Warning: Injury to device users may result if ...

A Warning identifies conditions or inappropriate usage of the product

that could lead to conditions that are potentially hazardous for devices

users. In the online version of this book, the word Warning appears

instead of this symbol.

Example Description







CrossCore Embedded Studio 1.1 1-1

C/C++ Library Manual for SHARC Processors

1 C/C++ RUN-TIME LIBRARY

The C and C++ run-time libraries are collections of functions, macros,

and class templates that you can call from your source programs. Many

functions are implemented in the ADSP-21xxx assembly language. C and

C++ programs depend on library functions to perform operations that are

basic to the C and C++ programming environments. These operations

include memory allocations, character and string conversions, and math

calculations. Using the library simplifies your software development by

providing code for a variety of common needs.

The sections of this chapter present the following information on the

compiler:

•C and C++ Run-Time Libraries Guide

provides introductory information about the ANSI/ISO standard

C and C++ libraries. It also provides information about the ANSI

standard header files and built-in functions that are included with

this release of the cc21k compiler.

•C Run-Time Library Reference

contains reference information about the C run-time library func-

tions included with this release of the cc21k compiler.

The cc21k compiler provides a broad collection of library functions,

including those required by the ANSI standard and additional functions

supplied by Analog Devices that are of value in signal processing applica-

tions. In addition to the standard C library, this release of the compiler

software includes the Abridged C++ library, a conforming subset of the

standard C++ library. The Abridged C++ library includes the embedded

C++ and embedded standard template libraries.

C and C++ Run-Time Libraries Guide

1-2 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

This chapter describes the standard C/C++ library functions that are sup-

ported in the current release of the run-time libraries. Chapter 2, DSP

Run-Time Library describes a number of signal processing, matrix, and

statistical functions that assist code development.

For more information on the algorithms on which many of the C

library’s math functions are based, see W. J, Cody and W. Waite,

Software Manual for the Elementary Functions, Englewood Cliffs,

New Jersey: Prentice Hall, 1980. For more information on the C++

library portion of the ANSI/ISO Standard for C++, see Plauger, P.

J. (Preface), The Draft Standard C++ Library, Englewood Cliffs,

New Jersey: Prentice Hall, 1994, (ISBN: 0131170031).

The Abridged C++ library software documentation is located in the CCES

online help.

C and C++ Run-Time Libraries Guide

The C and C++ run-time libraries contain routines that you can call from

your source program. This section describes how to use the libraries and

provides information on the following topics:

•Calling Library Functions

•Linking Library Functions

•Library Attributes

•Working With Library Header Files

•Calling Library Functions From an ISR

•Using the Libraries in a Multi-Threaded Environment

•Using Compiler Built-In C Library Functions

•Abridged C++ Library Support

CrossCore Embedded Studio 1.1 1-3

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

•Measuring Cycle Counts

•File I/O Support

•Fatal Error Handling

For information on the C library’s contents, see C Run-Time Library Ref-

erence. For information on the Abridged C++ library’s contents, see

Abridged C++ Library Support.

Calling Library Functions

To use a C/C++ library function, call the function by name and give the

appropriate arguments. The name and arguments for each function appear

on the function’s reference page. The reference pages appear in the

C Run-Time Library Reference.

Like other functions you use, library functions should be declared. Decla-

rations are supplied in header files. For more information about the

header files, see Working With Library Header Files.

Function names are C/C++ function names. If you call a C/C++ run-time

library function from an assembly program, you must use the assembly

version of the function name (prefix an underscore on the name). For

more information on the naming conventions, see Chapter 1 of the

C/C++ Compiler Manual for SHARC Processors.

You can use the archiver, elfar, described in the Linker and Utili-

ties Manual, to build library archive files of your own functions.

Linking Library Functions

When you call a run-time library function, the call creates a reference that

the linker resolves when linking your program. One way to direct the

linker to the library’s location is to use the default Linker Description File

(ADSP-<your_target>.ldf).

C and C++ Run-Time Libraries Guide

1-4 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

If you are not using the default .ldf file, then either add the appropriate

library/libraries to the .ldf file used for your project, or use the compiler’s

-l switch to specify the library to be added to the link line. For example,

the switches -lc -ldsp add libc.dlb and libdsp.dlb to the list of libraries

to be searched by the linker. For more information on the .ldf file, see

the Linker and Utilities Manual.

Functional Breakdown

The C/C++ run-time library is organized as several libraries:

• Compiler support library – Contains internal functions that sup-

port the in-line code generated by the compiler; emulated

arithmetic is a typical case.

• C run-time library – Comprises all the functions that are defined

by the ANSI standard, plus various Analog Devices extensions.

• DSP run-time library – Contains additional library functions sup-

plied by Analog Devices that provide services commonly required

by DSP applications.

• Heap debugging library – Contains debug versions of the heap sup-

port provided by the C/C++ run-time library, as well as some

additional diagnostic functions relating to heap use.

• Instrumented profiling library – Contains support routines for

recording the cycles spent in each profiled function.

• I/O library – Supports a subset of the C standard’s I/O

functionality.

• Dynamic module loader library – Supports loading and using

dynamically-loadable modules created using the elf2dyn utility.

CrossCore Embedded Studio 1.1 1-5

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

In addition to regular run-time libraries, CCES has some additional

libraries which provide variants of LibIO (the I/O run-time support

library). These variants are:

•libio*_lite.dlb – libraries which provide smaller versions of

LibIO with more limited functionality. These smaller LibIO librar-

ies can be used by specifying the following switch on the build

command line: -flags-link -MD__LIBIO_LITE

•libio*_fx.dlb – libraries which provide versions of LibIO with full

support for the fixed-point format specifiers for the fract types.

These libraries can be used by specifying the following switch on

the build command line: -flags-link -MD__LIBIO_FX

Library Location

The C/C++ run-time libraries are provided in binary form in directories

named sharc\lib\processor_rev_revision:

•processor identifies which processor for which the library is built,

and is the processor’s name with the leading “ADSP-” stripped.

•revision identifies for which silicon revision the library is built. For

example, a revision of 0.1 would indicate that the library was built

with the command-line switch -si-revision 0.1.

So the directory sharc\lib\21469_rev_any contains libraries that have

been built with -proc ADSP-21469 -si-revision any switches.

The C/C++ run-time libraries are provided in source form, where avail-

able, in the directories named sharc\lib\src\libname, where libname

indicates which library the source is used to build.

C and C++ Run-Time Libraries Guide

1-6 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

Library Selection

The library directory used to link an application is selected through the

-proc and -si-revision compiler switches, in conjunction with an XML

configuration file.

The -proc switch directs the compiler driver to read an XML configura-

tion file from System\ArchDef, based on the selected processor. For

example, a compiler switch of -proc ADSP-21469 would cause the com-

piler driver to read the ADSP-21469-compiler.xml file in System\ArchDef.

Each such XML file indicates which library subdirectory should be used,

for supported silicon revision of that processor. For example, the XML file

for the ADSP-21469 processor indicates that for silicon revision 0.2, the

library directory to use is sharc\lib\21469_rev_any.

A given library subdirectory might support more than one silicon revision.

In such cases, the XML file will give the same library subdirectory for sev-

eral silicon revisions.

Library Naming

Within the library subdirectories, the libraries follow a consistent naming

scheme, so that the library’s name will be lib<name><attrs>.dlb, where

name indicates the library’s purpose, and attrs is a sequence of zero or

more attributes. The libraries’ names are given in Table 1-2, and the attri-

butes are enumerated in Table 1-1.

CrossCore Embedded Studio 1.1 1-7

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

The run-time libraries and binary files for the ADSP-21160 processors in

this table have been compiled with the -workaround rframe compiler

switch, while those for the ADSP-21161 processors have been compiled

with the -workaround 21161-anomaly-45 switch.

The libraries for the ADSP-214xx processor are built in short-word mode.

Table 1-1. Library Name Attributes

Attribute Meaning

mt Built with -threads, for use in a multi-threaded environment

xBuilt with -eh -rtti, to enable C++ exception-handling

Table 1-2. C/C++ Library Names

Description Library Name Comments

Compiler support library libcc*.dlb

C run-time library libc*.dlb

C++ run-time library libcpp*.dlb

DSP run-time library libdsp*.dlb

Heap debugging library libheapdbg*.dlb

Instrumented profiling library libprofile*.dlb

I/O run-time library libio*.dlb

I/O run-time library with no

support for alternative device

drivers or printf(“%a”)

libio_lite*.dlb

I/O run-time library with full

support for the fixed-point for-

mat specifiers

libiofx*.dlb

Loader library for dynami-

cally-loadable modules (DLMs)

libdyn*.dlb Operates on DLMs pro-

duced by elf2dyn. Refer to

the Loader and Utilities

Manual.

C and C++ Run-Time Libraries Guide

1-8 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

Library Startup Files

The library subdirectories also contain object files which contain the “run-

time header”, or “C run-time” (CRT) startup code. These files contain the

code that is executed when your application first starts running; it is this

code that configures the expected C/C++ environment and passes control

to your main() function.

Startup files have names of the form procid_attrs_hdr.doj:

•procid indicates which processor the startup code is for; for

ADSP-211xx, ADSP-212xx and ADSP-213xx processors, this is

the last three digits of the processor’s name. For other processors,

this is the five digits of the processor’s name.

•attrs is a list of zero or more names indicating which features are

configured by the startup code. These attributes and their mean-

ings are listed in Table 1-3.

Library Attributes

The run-time libraries make use of file attributes. (See Chapter 1 of the

C/C++ Compiler Manual for SHARC Processors for more details on how to

use file attributes.) Each library function has a defined set of file attributes

that are listed in Table 1-4. For each object obj in the run-time libraries

the following is true.

Table 1-3. Startup File Attributes

Attribute Meaning

_cpp C++ startup file

_sov Enables stack overflow detection

CrossCore Embedded Studio 1.1 1-9

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

If an object in the run-time library calls into another object in the same

library, whether it is internal or publicly visible, the called object will

inherit extra libGroup and libFunc values from the caller.

Table 1-4. Run-Time Library Object Attributes

Attribute Name Meaning of Attribute and Value

libGroup A potentially multi-valued attribute. Each value is the name of a

header file that either defines obj, or that defines a function that

calls obj.

libName The name of the library that contains obj. For example, suppose

that obj were part of libdsp.dlb, then the value of the attribute

would be libdsp.

libFunc The name of all the functions in obj. libFunc will have multiple

values -both the C, and assembly linkage names will be listed.

libFunc will also contain all the published C and assembly link-

age names of objects in obj's library that call into obj.

prefersMem One of three values: internal, external or any. If obj contains

a function that is likely to be application performance critical, it

will be marked as internal. Most DSP run-time library func-

tions fit into the internal category. If a function is deemed

unlikely to be essential for achieving the necessary performance it

will be marked as external (all the I/O library functions fall into

this category). The default .ldf files use this attribute to place

code and data optimally.

prefersMemNum Analogous to prefersMem but takes a numeric string value. The

attribute can be used in .ldf files to provide a greater measure of

control over the placement of binary object files than is available

using the prefersMem attribute. The values "30", "50", and

"70" correspond to the prefersMem values internal, any, and

external respectively. The default .ldf files use the prefers-

Mem attribute in preference to the prefersMemNum attribute to

specify the optimum placement of files.

FuncName Multi-valued attribute whose values are all the assembler linkage

names of the defined names in obj.

C and C++ Run-Time Libraries Guide

1-10 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

The following example demonstrates how attributes would look in a small

example library libfunc.dlb that comprises three objects: func1.doj,

func2.doj and subfunc.doj. These objects are built from the following

source modules:

File: func1.h

void func1(void);

File: func2.h

void func2(void);

File: func1.c

#include func1.h”

void func1(void) {

/* Compiles to func1.doj */

subfunc();

}

File: func2.c

#include "func2.h"

void func2(void) {

/* Compiles to func2.doj */

subfunc();

}

File: subfunc.c

void subfunc(void) {

/* Compiles to subfunc.doj */

}

The objects in libfunc.dlb have the attributes as defined in Table 1-5.

CrossCore Embedded Studio 1.1 1-11

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

Table 1-5. Attribute Values in libfunc.dlb

Attribute Value

func1.doj

libGroup

libName

libFunc

FuncName

prefersMem

prefersMemNum

func1.h

libfunc

_func1

func1

_func1

any(1)

func2.doj

libGroup

libName

libFunc

FuncName

prefersMem

prefersMemNum

func2.h

libfunc

_func2

func2

_func2

internal(2)

subfunc.doj

libGroup

libName

libFunc

FuncName

prefersMem

prefersMemNum

func1.h

func2.h(3)

libfunc

_func1

func1

_func2

func2

_subfunc

subfunc

_subfunc

internal(4)

1 func1.doj will not be performance critical, based on its

normal usage.

2 func2.doj will be performance critical in many appli-

cations, based on its normal usage.

3 libGroup contains the union of the libGroup attributes

of the two calling objects.

4 prefersMem contains the highest priority of all the call-

ing objects.

C and C++ Run-Time Libraries Guide

1-12 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

Exceptions to the Attribute Conventions

The library attribute convention has the following exceptions:

The C++ support libraries (libcpp*.dlb) all contain functions that have

C++ linkage. Functions written in C++ have their functions names

encoded (often referred to as name mangling) to allow for the overloading

of parameter types. The function name encoding includes all the parame-

ter types, the return type and the namespace within which the function is

declared. Whenever a function’s name is encoded, the encoded name is

used as the value for the libFunc attribute.

Table 1-6 lists additional libGroup attribute values.

Objects with any of the libGroup attribute values listed in Table 1-6 will

not contain any libGroup or libFunc attributes from any calling objects.

Table 1-6. Additional libGroup Attribute Values

Value Meaning

floating_point_support Compiler support routines for floating-point arithmetic

fixed_point_support Compiler support routines for native fixed-point types

integer_support Compiler support routines for integer arithmetic

runtime_support Other run-time functions that do not fit into any of the above

See Also

raise, signal

CrossCore Embedded Studio 1.1 1-67

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

abs

Absolute value

Synopsis

#include <stdlib.h>

int abs (int j);

Description

The abs function returns the absolute value of its integer argument.

Note: abs(INT_MIN) returns INT_MIN.

Error Conditions

None.

Example

#include <stdlib.h>

int i;

i = abs (-5); /* i == 5 */

See Also

fabs, absfx, labs, llabs

Documented Library Functions

1-68 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

absfx

absolute value

Synopsis

#include <stdfix.h>

short fract abshr(short fract f);

fract absr(fract f);

long fract abslr(long fract f);

Description

The absfx family of functions return the absolute value of their fixed-point

input. In addition to the individually-named functions for each

fixed-point type, a type-generic macro absfx is defined for use in C99

mode. This may be used with any of the fixed-point types and returns a

result of the same type as its operand.

Error Conditions

None.

Example

#include <stdfix.h>

long fract f;

f = abslr(0.75lr); /* f == 0.75lr */

f = absfx(0.75lr); /* f == 0.75lr */

See Also

abs, fabs, labs, llabs

CrossCore Embedded Studio 1.1 1-69

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

acos

Arc cosine

Synopsis

#include <math.h>

float acosf (float x);

double acos (double x);

long double acosd (long double x);

Description

The arc cosine functions return the arc cosine of x. The input must be in

the range [-1, 1]. The output, in radians, is in the range [0, ].

Error Conditions

The arc cosine functions indicate a domain error (set errno to EDOM) and

return a zero if the input is not in the range [–1, 1].

Example

#include <math.h>

double x;

float y;

x = acos (0.0); /* x = /2 */

y = acosf (0.0); /* y = /2 */

See Also

cos

Documented Library Functions

1-70 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

adi_dump_all_heaps

Dump the current state of current heaps to a file

Synopsis

#include <heap_debug.h>

void adi_dump_all_heaps(char *filename);

Description

The adi_dump_all_heaps function writes the current state of all of the

heaps known to the heap debugging library to the file specified by file-

name. The information written to the file consists of the address, size and

state of any blocks on that heap that have been tracked by the heap debug-

ging library, and the total memory currently allocated from that heap.

If the specified file exists, then the file is appended to; otherwise, a new

file is created.

The adi_dump_all_heaps function relies on the heap usage being

tracked by the heap debugging library, any heap activity which is

carried out when heap usage is not being tracked (when heap

debugging is paused or disabled) will not be included in the

output.

The adi_heap_dump_all_heaps should be called only when it is safe

to carry out I/O operations. Calling adi_adi_dump_all_heaps from

within an interrupt or an unscheduled region will result in adi_fa-

tal_error being called.

For more information on heap debugging, see the section “Heap Debug-

ging” in Chapter 2 of the C/C++ Compiler Manual for SHARC Processors.

CrossCore Embedded Studio 1.1 1-71

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

Error Conditions

The adi_dump_heap function calls adi_fatal_error if it is unable to

open the requested file.

Example

#include <heap_debug.h>

#include <stdio.h>

void dump_heaps()

{

adi_dump_all_heaps(“./dumpfile.txt”);

}

See Also

adi_dump_heap, adi_fatal_error

Documented Library Functions

1-72 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

adi_dump_heap

Dump the current state of a heap to a file

Synopsis

#include <heap_debug.h>

bool adi_dump_heap(char *filename, int heapindex);

Description

The adi_dump_heap function writes the current state of the heap identi-

fied by heapindex to the file specified by filename. The information

written to the file consists of the address, size and state of any blocks on

that heap tracked by the heap debugging library, and the total memory

currently allocated from that heap.

If the specified file exists, then the file is appended to, otherwise a new file

is created.

The adi_dump_heap function relies on the heap usage being

tracked by the heap debugging library. Any heap activity which is

carried out when heap usage is not being tracked (when heap

debugging is paused or disabled) will not be included in the

output.

The adi_heap_dump_heap function should be called only when it

is safe to carry out I/O operations. Calling adi_adi_dump_heap

from within an interrupt or an unscheduled region will result in

adi_fatal_error being called

For more information on heap debugging, see the section “Heap Debug-

ging” in Chapter 2 of the C/C++ Compiler Manual for SHARC Processors.

CrossCore Embedded Studio 1.1 1-73

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

Error Conditions

The adi_dump_heap function calls adi_fatal_error if it is unable to

open the requested file.

Example

#include <heap_debug.h>

#include <stdio.h>

void dump_heap(int heapindex)

{

if (!adi_dump_heap(“./dumpfile.txt”, heapindex)) {

printf(“heap %d does not exist\n”, heapindex);

}

See Also

adi_dump_all_heaps, adi_fatal_error

Documented Library Functions

1-74 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

adi_fatal_error

Handle a non-recoverable error

Synopsis

#include <stdlib.h>

void adi_fatal_error(int general_code,

int specific_code,

int value);

Description

The adi_fatal_error function handles a non-recoverable error. The param-

eters general_code,specific_code and value will be written to global

variables along with the return address, before looping around the label

__fatal_error.

The adi_fatal_error function can be jumped to rather than called in order

to preserve the return address if required.

See Fatal Error Handling for more information.

Error Conditions

None.

Example

#include <stdlib.h>

#define MY_GENERAL_CODE (0x9)

void non_recoverable_error(int code, int value) {

adi_fatal_error(MY_GENERAL_CODE, code, value);

}

CrossCore Embedded Studio 1.1 1-75

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

See Also

adi_fatal_exception

Documented Library Functions

1-76 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

adi_fatal_exception

Handle a non-recoverable exception

Synopsis

#include <stdlib.h>

void adi_fatal_exception(int general_code,

int specific_code,

int value);

Description

The adi_fatal_exception function handles a non-recoverable exception.

The parameters general_code, specific_code and value will be written

to global variables along with the return address, before looping around

the label __fatal_exception.

The adi_fatal_exception function can be jumped to rather than called in

order to preserve the return address if required.

See Fatal Error Handling for more information.

Error Conditions

None.

Example

#include <stdlib.h>

#define MY_GENERAL_CODE (0x9)

void non_recoverable_exception(int code, int value) {

adi_fatal_exception(MY_GENERAL_CODE, code, value);

}

CrossCore Embedded Studio 1.1 1-77

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

See Also

adi_fatal_error

Documented Library Functions

1-78 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

adi_heap_debug_disable

Disable features of the heap debugging

Synopsis

#include <heap_debug.h>

void adi_heap_debug_disable(unsigned char flag);

Description

The adi_heap_debug_disable function accepts a bit-field parameter detail-

ing which features are to be enabled. These bits are represented by macros

defined in heap_debug.h.

These parameter bits can be combined using the bitwise OR operator to

allow multiple settings to be disabled at once.

For more information on heap debugging, see the section “Heap Debug-

ging” in Chapter 2 of the C/C++ Compiler Manual for SHARC Processors.

Error Conditions

None.

Example

#include <heap_debug.h>

void disable_diagnostics()

{

// Disable run-time errors

adi_heap_debug_disable(_HEAP_STDERR_DIAG);

}

CrossCore Embedded Studio 1.1 1-79

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

See Also

adi_heap_debug_enable

Documented Library Functions

1-80 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

adi_heap_debug_enable

Enable features of the heap debugging

Synopsis

#include <heap_debug.h>

void adi_heap_debug_enable(unsigned char flag);

Description

The adi_heap_debug_enable function accepts a bit-field parameter detail-

ing which features are to be enabled. These bits are represented by macros

defined in heap_debug.h. _HEAP_TRACK_USAGE (track heap activity) is

implicitly enabled when either _HEAP_STDERR_DIAG (generate diagnostics

at runtime) or _HEAP_HPL_GEN (generate .hpl file of heap activity used by

report) are enabled.

These parameter bits can be combined using the bitwise OR operator to

allow multiple settings to be enabled at once.

For more information on heap debugging, see section “Heap Debugging”

in Chapter 2 of the C/C++ Compiler Manual for SHARC Processors.

Error Conditions

None.

Example

#include <heap_debug.h>

void enable_hpl_gen()

{

// Enable run-time errors and the generation of the .hpl file

adi_heap_debug_enable(_HEAP_STDERR_DIAG | _HEAP_HPL_GEN);

}

CrossCore Embedded Studio 1.1 1-81

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

See Also

adi_heap_debug_disable

Documented Library Functions

1-82 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

adi_heap_debug_end

Finish heap debugging

Synopsis

#include <heap_debug.h>

void adi_heap_debug_end(void);

Description

The adi_heap_debug_end function records the end of the heap

debugging.

Internal data used by the heap debugging library will be freed, the .hpl

file generated will be closed (if .hpl generation is enabled) and any heap

corruption or memory leaks will be reported. The adi_heap_debug_end

function can be called multiple times, allowing heap debugging to be

started and ended over specific sections of code.

Use adi_heap_debug_end in non-terminating applications to instruct the

heap debugging library to carry out the end checks for the heap debugging

in that application.

Do not call adi_heap_debug_end from within an ISR or when thread

switching as there will be no way for it to produce any output.

For more information on heap debugging, see section “Heap Debugging”

in Chapter 2 of the C/C++ Compiler Manual for SHARC Processors.

Error Conditions

Corrupt blocks or memory leaks may be reported via the console view (if

run-time diagnostics are enabled) or via the report (if .hpl file generation

is enabled).

CrossCore Embedded Studio 1.1 1-83

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

Example

#include <heap_debug.h>

void main_func()

{

// Start heap debugging

adi_heap_debug_enable(_HEAP_STDERR_DIAG);

// Application code

run_application();

// Check for leaks or corruption

adi_heap_debug_end();

}

See Also

adi_heap_debug_enable

Documented Library Functions

1-84 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

adi_heap_debug_flush

Flush the heap debugging output buffer

Synopsis

#include <heap_debug.h>

void adi_heap_debug_flush(void);

Description

The adi_heap_debug_flush function flushes any buffered data to the .hpl

file used by the reporter tool to generated the heap debugging report.

The adi_heap_debug_flush function should only be called when it

is safe to carry out I/O operations. Calling adi_heap_debug_flush

from within an interrupt or an unscheduled region will result in

adi_fatal_error being called.

For more information on heap debugging, see the section “Heap Debug-

ging” in Chapter 2 of the C/C++ Compiler Manual for SHARC Processors.

Error Conditions

The adi_heap_debug_flush function calls adi_fatal_error if called when

it is unsafe to use I/O.

Example

#include <heap_debug.h>

void flush_hpl_buffer()

{

adi_heap_debug_flush();

}

CrossCore Embedded Studio 1.1 1-85

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

See Also

adi_fatal_error

Documented Library Functions

1-86 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

adi_heap_debug_pause

Temporarily disable the heap debugging

Synopsis

#include <heap_debug.h>

void adi_heap_debug_pause(void);

Description

The adi_heap_debug_pause function disables the heap debugging func-

tionality. When disabled, the heap debugging library has a minimal

performance overhead compared to the non-debug versions of the heap

debugging functions provided by the C/C++ run-time libraries. Pausing

heap debugging means that any heap operations, which happen between

pausing and re-enabling the heap debugging, will not be tracked, meaning

that erroneous behavior may not be detected and false errors regarding

unfreed blocks or unknown addresses may be reported.

Take care when using adi_heap_debug_pause in a threaded environment,

as the heap debugging will be disabled globally rather than within the con-

text of the current thread.

For more information on heap debugging, see the section “Heap Debug-

ging” in Chapter 2 of the C/C++ Compiler Manual for SHARC Processors.

Error Conditions

None.

CrossCore Embedded Studio 1.1 1-87

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

Example

#include <heap_debug.h>

void a_performance_critical_function(void);

void performance_critical_fn_wrapper()

{

adi_heap_debug_pause();

a_performance_critical_function();

adi_heap_debug_resume();

}

See Also

adi_heap_debug_resume

Documented Library Functions

1-88 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

adi_heap_debug_reset_guard_region

Reset guard regions to default values

Synopsis

#include <heap_debug.h>

bool adi_heap_debug_reset_guard_region(void);

Description

The adi_heap_debug_reset_guard_region function resets the guard region

values to the default. The heaps are checked for guard region corruption

before all existing guard regions are replaced with the new values. If cor-

ruption is detected, then no guard regions are changed and

adi_heap_debug_reset_guard_region returns false. The contents of exist-

ing allocated blocks are not changed, but any newly allocated blocks are

pre-filled with the new allocated block pattern.

The default reset values are detailed in Table 1-34.

For more information on heap debugging, see the section “Heap Debug-

ging” in Chapter 2 of the C/C++ Compiler Manual for SHARC Processors.

Error Conditions

The adi_heap_debug_reset_guard_region function returns false if no

guard region change was made, due to the detection of corruption on one

of the heaps.

Table 1-34. Reset Values for Heap Guard Regions

Region Value

Free block 0xBDBDBDBD

Allocated block 0xDDDDDDDD

Block content (not calloc)0xEDEDEDED

CrossCore Embedded Studio 1.1 1-89

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

Example

#include <heap_debug.h>

#include <stdio.h>

void reset_guard_region()

{

if (!adi_heap_debug_reset_guard_region()) {

printf(“couldn’t reset guard regions\n”);

}

See Also

adi_heap_debug_set_guard_region

Documented Library Functions

1-90 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

adi_heap_debug_resume

Re-enable the heap debugging

Synopsis

#include <heap_debug.h>

void adi_heap_debug_resume(void);

Description

The adi_heap_debug_resume function enables the heap debugging. Any

allocations or de-allocations that occurred when the heap debugging was

disabled will not have been tracked by the heap debugging library, so false

errors regarding invalid addresses or memory leaks may be produced.

For more information on heap debugging, see section “Heap Debugging”

in Chapter 2 of the C/C++ Compiler Manual for SHARC Processors.

Error Conditions

None.

Example

#include <heap_debug.h>

void a_performance_critical_function(void);

void performance_critical_fn_wrapper()

{

adi_heap_debug_pause();

a_performance_critical_function();

adi_heap_debug_resume();

}

CrossCore Embedded Studio 1.1 1-91

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

See Also

adi_heap_debug_pause

Documented Library Functions

1-92 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

adi_heap_debug_set_buffer

Configure a buffer to be used by the heap debugging

Synopsis

#include <heap_debug.h>

bool adi_heap_debug_set_buffer(void *ptr, size_t size,

size_t threshold);

Description

The adi_heap_debug_set_buffer function instructs the heap debugging

library to use the specified buffer for the writing of the .hpl file used by

the Reporter Tool to generate a heap debugging report. The buffer is of

size addressable units starting at address ptr, with a flush threshold of

threshold addressable units. The minimum size of the buffer in address-

able units can be determined using the macro _ADI_HEAP_MIN_BUFFER

(defined in heap_debug.h) and represents the memory required to store

two entries of the heap debugging buffer along with associated call stacks.

Changing the call stack depth after setting a buffer may alter the number

of entries which can be held within the buffer.

Buffering can be disabled by calling adi_heap_debug_set_buffer with a

null pointer as the first parameter.

Using a buffer will reduce the number of I/O operations to write the .hpl

file to the host which should in turn result in a significant reduction in

execution time when running applications which make frequent use of the

heap.

If the buffer is full or no buffer is specified, and heap activity occurs where

I/O is not permitted, that data will be lost.

The buffer will be flushed automatically when it is filled beyond a capacity

threshold, specified by the threshold parameter, and it is safe to flush.

Flushing can be triggered manually by calling adi_heap_debug_flush.

CrossCore Embedded Studio 1.1 1-93

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

For more information on heap debugging, see “Heap Debugging” in the

C/C++ Compiler Manual for SHARC Processors.

Only call adi_heap_debug_set_buffer when it is safe to carry out

I/O operations. Calling adi_heap_debug_set_buffer from within

an interrupt or an unscheduled region will result in adi_fatal_error

being called.

Error Conditions

The adi_heap_debug_set_buffer function returns false if the buffer passed

is not valid or big enough to be used the heap debugging library.

Example

#include <heap_debug.h>

char heapbuffer[1024];

bool set_buffer(void)

{

if (sizeof(heapbuffer) < _ADI_HEAP_MIN_BUFFER) {

return false;

}

return adi_heap_debug_set_buffer(&heapbuffer,

sizeof(heapbuffer),

sizeof(heapbuffer)/2);

}

Documented Library Functions

1-94 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

adi_heap_debug_set_call_stack_depth

Change the depth of the call stack recorded by the heap debugging library

Synopsis

#include <heap_debug.h>

bool adi_heap_debug_set_call_stack_depth(unsigned int depth);

Description

The adi_heap_debug_set_call_stack_depth function sets the maximum

depth of the call stack recorded by the heap debugging library for use in

the heap reports and diagnostic messages. The memory for the call stack is

allocated from the system heap and requires memory of size

(2*sizeof(int)) per call stack element. The default value is 5 stack ele-

ments deep.

The adi_heap_debug_set_call_stack_depth function returns true if it is

able to change the depth; otherwise, false is returned and the depth

remains unchanged.

For more information on heap debugging, see the section “Heap Debug-

ging” in Chapter 2 of the C/C++ Compiler Manual for SHARC Processors.

Error Conditions

The adi_heap_debug_set_call_stack_depth function returns false if it is

unable to allocate sufficient memory for the new call stack.

CrossCore Embedded Studio 1.1 1-95

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

Example

#include <heap_debug.h>

#include <stdio.h>

bool set_call_stack_depth(unsigned int size)

{

if (!adi_heap_debug_set_call_stack_depth(size)) {

printf(“unable to set heap debug call stack ”

“to %d elements\n”, size);

return false;

}

return true;

}

See Also

No related functions.

Documented Library Functions

1-96 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

adi_heap_debug_set_error

Change error types to be regarded as terminating errors

Synopsis

#include <heap_debug.h>

void adi_heap_debug_set_error(unsigned long flag);

Description

The adi_heap_debug_set_error function changes the severity of the speci-

fied types of heap error to a terminating run-time error. These types are

represented as a bit-field using macros defined in heap_debug.h.

Terminating run-time errors print a diagnostic message to stderr before

calling adi_fatal_error.

Run-time errors need to be enabled for these changes to have any

effect.

For more information on heap debugging, see the section “Heap Debug-

ging” in Chapter 2 of the C/C++ Compiler Manual for SHARC Processors.

Error Conditions

None.

Example

#include <heap_debug.h>

void set_errors()

{

/* Enable run-time diagnostics */

adi_heap_debug_enable(_HEAP_STDERR_DIAG);

CrossCore Embedded Studio 1.1 1-97

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

/* Regard frees from the wrong heap or of null pointers */

/* as terminating run-time errors */

adi_heap_debug_set_error(_HEAP_ERROR_WRONG_HEAP |

_HEAP_ERROR_NULL_PTR );

}

See Also

adi_heap_debug_enable, adi_heap_debug_set_ignore,

adi_heap_debug_set_warning

Documented Library Functions

1-98 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

adi_heap_debug_set_guard_region

Changes the bit patterns written to guard regions around memory blocks

Synopsis

#include <heap_debug.h>

bool adi_heap_debug_set_guard_region(unsigned char free,

unsigned char allocated,

unsigned char content);

Description

The adi_heap_debug_set_guard_region function changes the bit pattern

written to the guard regions around memory blocks used by the heap

debugging library to check, if overwriting has occurred. The heaps are

checked for guard region corruption before changing the guard regions. If

any guard region is corrupt then adi_heap_debug_set_guard_region fails

and the guard regions will not be changed. The contents of existing alloca-

tions are not be changed, but any new allocations will be pre-filled with

the pattern specified by the allocated parameter.

The value of free is written to any free blocks, as well as the following

guard region. Corruption of these blocks indicates that a pointer has been

used to write to a block after it has been freed.

The value of allocated is written to the guard regions on either side of

the allocated block. Corruption of these blocks indicates that overflow or

underflow of that allocation has occurred.

The value of content is written to the allocated memory block, with the

exception of memory allocated by calloc, which is zero filled. Seeing this

value in live data indicates that memory allocated from the heap is used

before being initialized.

CrossCore Embedded Studio 1.1 1-99

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

The current values for the guard regions for free blocks, allocated blocks,

and the pattern used for allocated block contents are stored in the “C”

char variables adi_heap_guard_free, adi_heap_guard_alloc, and

adi_heap_guard_content. These variables can be defined at build-time

but should not be written to directly at run-time or false corruption errors

may be reported.

The guard region values can be reset to the ADI default values by calling

adi_heap_debug_reset_guard_region.

For more information on heap debugging, see “Heap Debugging” in

Chapter 2 of the C/C++ Compiler Manual for SHARC Processors.

Error Conditions

The adi_heap_debug_set_guard_region function returns false if it was

unable to change the guard regions, due the presence of block corruption

on one of the heaps.

Example

#include <heap_debug.h>

#include <stdio.h>

bool set_guard_regions()

{

if (!adi_heap_debug_set_guard_region(0x11111111,

0x22222222,

0x33333333) {

printf(“failed to change guard regions\n”);

return false;

}

return true;

}

Documented Library Functions

1-100 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

See Also

adi_heap_debug_reset_guard_region

CrossCore Embedded Studio 1.1 1-101

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

adi_heap_debug_set_ignore

Change error types to be ignored

Synopsis

#include <heap_debug.h>

void adi_heap_debug_set_ignore(unsigned long flag);

Description

The adi_heap_debug_set_ignore function configures an error class as

ignored. These types are represented as a bit-field using macros defined in

heap_debug.h.

Ignored errors produce no run-time diagnostics, but will appear in the

heap debugging report (if generated).

Run-time errors need to be enabled for these changes to have any

effect.

For more information on heap debugging, see the section “Heap Debug-

ging” in Chapter 2 of the C/C++ Compiler Manual for SHARC Processors.

Error Conditions

None.

Example

#include <heap_debug.h>

void ignore_unwanted_errors()

{

// Enable run-time diagnostics

adi_heap_debug_enable(_HEAP_STDERR_DIAG);

Documented Library Functions

1-102 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

// Don’t produce run-time diagnostics about frees

// from the wrong heap or heap operations used

// from within an interrupt

adi_heap_debug_set_ignore(_HEAP_ERROR_WRONG_HEAP |

_HEAP_ERROR_IN_ISR);

}

See Also

adi_heap_debug_enable, adi_heap_debug_set_error,

adi_heap_debug_set_warning

CrossCore Embedded Studio 1.1 1-103

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

adi_heap_debug_set_warning

Change error types to be regarded as run-time warning

Synopsis

#include <heap_debug.h>

void adi_heap_debug_set_warning(unsigned long flag);

Description

The adi_heap_debug_set_warning function configures an error class to be

regarded as a warning. These types are represented as a bit-field using

macros defined in heap_debug.h.

A warning diagnostic is produced at runtime if an error of that class is

detected, but the application will not terminate.

Any detected errors are recorded in the heap debugging report (if gener-

ated) as normal.

If the heap debugging library is unable to write a warning to stderr due to

being in an interrupt or an unscheduled region, then the warning will be

treated as an error and adi_fatal_error will be called. For this reason,

setting _HEAP_ERROR_IN_ISR (heap usage within interrupt) to be a warning

has no effect.

Run-time errors need to be enabled for these changes to have any

effect.

For more information on heap debugging, see the section “Heap Debug-

ging” in Chapter 2 of the C/C++ Compiler Manual for SHARC Processors.

Error Conditions

None.

Documented Library Functions

1-104 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

Example

#include <heap_debug.h>

void set_warnings()

{

// Enable run-time diagnostics

adi_heap_debug_enable(_HEAP_STDERR_DIAG);

// Produce warnings about de-allocating and

// reallocating pointers not returned by an

// allocation function and about de-allocations

// not using functions which correspond to an

// allocation, but don’t terminate the application

// on detection

adi_heap_debug_set_warning(_HEAP_ERROR_INVALID_ADDRESS |

_HEAP_ERROR_FUNCTION_MISMATCH);

}

See Also

adi_heap_debug_enable, adi_heap_debug_set_error,

adi_heap_debug_set_ignore

CrossCore Embedded Studio 1.1 1-105

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

adi_verify_all_heaps

Verify that no heaps contain corrupt blocks

Synopsis

#include <heap_debug.h>

bool adi_verify_all_heaps(void);

Description

The adi_verify_all_heaps function checks that each heap tracked by the

heap debugging library contains no corrupted guard regions and that the

underlying heap structure is correct. If a corrupt guard region is detected

on any heaps then adi_verify_all_heaps will return false, otherwise

true will be returned.

The adi_verify_all_heaps function relies on the heap usage being

tracked by the heap debugging library. Any heap activity carried

out when heap usage is not being tracked (when heap debugging is

paused or disabled) is not checked for corruption.

For more information on heap debugging, see the section “Heap Debug-

ging” in Chapter 2 of the C/C++ Compiler Manual for SHARC Processors.

Error Conditions

The adi_verify_all_heaps function returns false if any corrupt guard

regions are detected on any heap.

Example

#include <heap_debug.h>

#include <stdio.h>

void check_heaps()

{

Documented Library Functions

1-106 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

if (!adi_verify_all_heaps()) {

printf(“heaps contain corruption\n”);

} else {

printf(“heaps are ok\n”);

}

See Also

adi_verify_heap

CrossCore Embedded Studio 1.1 1-107

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

adi_verify_heap

Verify that a heap contains no corrupt blocks

Synopsis

#include <heap_debug.h>

bool adi_verify_heap(int heapindex);

Description

The adi_verify_heap function checks that the heap specified with the

index heapindex has no corrupt guard regions. If any guard region corrup-

tion is detected on that heap then adi_verify_heap returns false;

otherwise, true is returned.

The heap index of static heaps can be identified by using heap_malloc.

The heap index of a dynamically defined heap is the value returned from

heap_install.

The adi_verify_heap function relies on the heap usage being

tracked by the heap debugging library. Any heap activity carried

out when heap usage is not being tracked (when heap debugging is

paused or disabled) is not be checked for corruption.

For more information on heap debugging, see the section “Heap Debug-

ging” in Chapter 2 of the C/C++ Compiler Manual for SHARC Processors.

Error Conditions

The adi_verify_heap function returns false if any corrupt guard regions

are detected on the specified heap.

Documented Library Functions

1-108 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

Example

#include <heap_debug.h>

#include <stdio.h>

void check_heap(int heapindex)

{

if (!adi_verify_heap(heapindex)) {

printf(“heap %d contain corruption\n”, heapindex);

} else {

printf(“heap %d is ok\n”, heapindex);

}

See Also

adi_verify_all_heaps

CrossCore Embedded Studio 1.1 1-109

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

asctime

Convert broken-down time into a string

Synopsis

#include <time.h>

char *asctime(const struct tm *t);

Description

The asctime function converts a broken-down time, as generated by the

functions gmtime and localtime, into an ASCII string that will contain

the date and time in the form

DDD MMM dd hh:mm:ss YYYY\n

where

•DDD represents the day of the week (that is, Mon, Tue, Wed, etc.)

•MMM is the month and will be of the form Jan, Feb, Mar, etc

•dd is the day of the month, from 1 to 31

•hh is the number of hours after midnight, from 0 to 23

•mm is the minute of the day, from 0 to 59

•ss is the second of the day, from 0 to 61 (to allow for leap seconds)

•YYYY represents the year

The function returns a pointer to the ASCII string, which may be over-

written by a subsequent call to this function. Also note that the function

ctime returns a string that is identical to

asctime(localtime(&t))

Documented Library Functions

1-110 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

Error Conditions

None.

Example

#include <time.h>

#include <stdio.h>

struct tm tm_date;

printf("The date is %s",asctime(&tm_date));

See Also

ctime, gmtime, localtime

CrossCore Embedded Studio 1.1 1-111

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

asin

Arc sine

Synopsis

#include <math.h>

float asinf (float x);

double asin (double x);

long double asind (long double x);

Description

The arc sine functions return the arc sine of the first argument. The input

must be in the range [1, 1]. The output, in radians, is in the range - to

.

Error Conditions

The arc sine functions indicate a domain error (set errno to EDOM) and

return a zero if the input is not in the range [-1, 1].

Example

#include <math.h>

double y;

float x;

y = asin (1.0); /* y = /2 */

x = asinf (1.0); /* x = /2 */

See Also

sin

Documented Library Functions

1-112 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

atan

Arc tangent

Synopsis

#include <math.h>

float atanf (float x);

double atan (double x);

long double atand (long double x);

Description

The arc tangent functions return the arc tangent of the first argument.

The output, in radians, is in the range - to .

Error Conditions

None.

Example

#include <math.h>

double y;

float x;

y = atan (0.0); /* y = 0.0 */

x = atanf (0.0); /* x = 0.0 */

See Also

atan2, tan

CrossCore Embedded Studio 1.1 1-113

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

atan2

Arc tangent of quotient

Synopsis

#include <math.h>

float atan2f (float y, float x);

double atan2 (double y, double x);

long double atan2d (long double y, long double x);

Description

The atan2 functions compute the arc tangent of the input value y divided

by input value x. The output, in radians, is in the range - to .

Error Conditions

The atan2 functions return a zero if x=0 and y=0.

Example

#include <math.h>

double a,d;

float b,c;

a = atan2 (0.0, 0.0); /* the error condition: a = 0.0 */

b = atan2f (1.0, 1.0); /* b = /4 */

c = atan2f (1.0, 0.0); /* c = /2 */

d = atan2 (-1.0, 0.0); /* d = -/2 */

See Also

atan, tan

Documented Library Functions

1-114 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

atexit

Synopsis

#include <stdlib.h>

int atexit (void (*func)(void));

Description

The atexit function registers a function to be called at program termina-

tion. Functions are called once for each time they are registered, in the

reverse order of registration. Up to 32 functions can be registered using

the atexit function.

Error Conditions

The atexit function returns a non-zero value if the function cannot be

registered.

Example

#include <stdlib.h>

extern void goodbye(void);

if (atexit(goodbye))

exit(1);

See Also

abort, exit

CrossCore Embedded Studio 1.1 1-115

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

atof

Convert string to a double

Synopsis

#include <stdlib.h>

double atof(const char *nptr);

Description

The atof function converts a character string into a floating-point value of

type double, and returns its value. The character string is pointed to by

the argument nptr and may contain any number of leading whitespace

characters (as determined by the function isspace) followed by a

floating-point number. The floating-point number may either be a deci-

mal floating-point number or a hexadecimal floating-point number.

A decimal floating-point number has the form:

[sign] [digits] [.digits] [{e|E} [sign] [digits]]

The sign token is optional and is either plus ( + ) or minus ( – ); and

digits are one or more decimal digits. The sequence of digits may contain

a decimal point ( . ).

The decimal digits can be followed by an exponent, which consists of an

introductory letter (e or E ) and an optionally signed integer. If neither an

exponent part nor a decimal point appears, a decimal point is assumed to

follow the last digit in the string.

The form of a hexadecimal floating-point number is:

[sign] [{0x}|{0X}] [hexdigs] [.hexdigs] [{p|P} [sign] [digits]]

A hexadecimal floating-point number may start with an optional plus ( + )

or minus ( - ) followed by the hexadecimal prefix 0x or 0X. This character

Documented Library Functions

1-116 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

sequence must be followed by one or more hexadecimal characters that

optionally contain a decimal point ( . ).

The hexadecimal digits are followed by a binary exponent that consists of

the letter p or P, an optional sign, and a non-empty sequence of decimal

digits. The exponent is interpreted as a power of two that is used to scale

the fraction represented by the tokens [hexdigs] [.hexdigs].

The first character that does not fit either form of number stops the scan.

Error Conditions

The atof function returns a zero if no conversion could be made. If the

correct value results in an overflow, a positive or negative (as appropriate)

HUGE_VAL is returned. If the correct value results in an underflow, 0.0 is

returned. The ERANGE value is stored in errno in the case of either an over-

flow or underflow.

Notes

The atof (pdata) function reference is functionally equivalent to:

strtod (pdata, (char *) NULL);

and therefore, if the function returns zero, it is not possible to determine

whether the character string contained a (valid) representation of 0.0 or

some invalid numerical string.

Example

#include <stdlib.h>

double x;

x = atof("5.5"); /* x = 5.5 */

CrossCore Embedded Studio 1.1 1-117

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

See Also

atoi, atol, atoll, strtod

Documented Library Functions

1-118 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

atoi

Convert string to integer

Synopsis

#include <stdlib.h>

int atoi (const char *nptr);

Description

The atoi function converts a character string to an integer value. The char-

acter string to be converted is pointed to by the input pointer, nptr. The

function clears any leading characters for which isspace would return

true. Conversion begins at the first digit (with an optional preceding sign)

and terminates at the first non-digit.

Error Conditions

The atoi function returns 0 if no conversion can be made.

Example

#include <stdlib.h>

int i;

i = atoi ("5"); /* i = 5 */

See Also

atof, atol, atoll, strtod

CrossCore Embedded Studio 1.1 1-119

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

atol

Convert string to long integer

Synopsis

#include <stdlib.h>

long atol (const char *nptr);

Description

The atol function converts a character string to a long integer value. The

character string to be converted is pointed to by the input pointer, nptr.

The function clears any leading characters for which isspace would return

true. Conversion begins at the first digit (with an optional preceding sign)

and terminates at the first non-digit.

There is no way to determine if a zero is a valid result or an indica-

tor of an invalid string.

Error Conditions

The atol function returns 0 if no conversion can be made.

Example

#include <stdlib.h>

long int i;

i = atol ("5"); /* i = 5 */

See Also

atof, atoi, atoll, strtod, strtol, strtoll, strtoul, strtoull

Documented Library Functions

1-120 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

atold

Convert string to a long double

Synopsis

#include <stdlib.h>

long double atold(const char *nptr);

Description

The atold function is an extension to the ISO/IEC 9899:1990 C standard

and the ISO/IEC 9899:1999 C standard.

The atold function converts a character string into a floating-point value

of type long double, and returns its value. The character string is pointed

to by the argument nptr and may contain any number of leading

whitespace characters (as determined by the function isspace) followed

by a floating-point number. The floating-point number may either be a

decimal floating-point number or a hexadecimal floating-point number.

A decimal floating-point number has the form:

[sign] [digits] [.digits] [{e|E} [sign] [digits]]

The sign token is optional and is either plus ( + ) or minus ( – ); and

digits are one or more decimal digits. The sequence of digits may contain

a decimal point ( . ).

The decimal digits can be followed by an exponent, which consists of an

introductory letter (e or E ) and an optionally signed integer. If neither an

exponent part nor a decimal point appears, a decimal point is assumed to

follow the last digit in the string.

The form of a hexadecimal floating-point number is:

[sign] [{0x}|{0X}] [hexdigs] [.hexdigs] [{p|P} [sign] [digits]]

CrossCore Embedded Studio 1.1 1-121

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

A hexadecimal floating-point number may start with an optional plus ( + )

or minus ( - ) followed by the hexadecimal prefix 0x or 0X. This character

sequence must be followed by one or more hexadecimal characters that

optionally contain a decimal point ( . ).

The hexadecimal digits are followed by a binary exponent that consists of

the letter p or P, an optional sign, and a non-empty sequence of decimal

digits. The exponent is interpreted as a power of two that is used to scale

the fraction represented by the tokens [hexdigs] [.hexdigs].

The first character that does not fit either form of number stops the scan.

Error Conditions

The atold function returns a zero if no conversion could be made. If the

correct value results in an overflow, a positive or negative (as appropriate)

LDBL_MAX is returned. If the correct value results in an underflow, 0.0 is

returned. The ERANGE value is stored in errno in the case of either an over-

flow or underflow.

Notes

The atold (pdata) function reference is functionally equivalent to:

strtold (pdata, (char *) NULL);

and therefore, if the function returns zero, it is not possible to determine

whether the character string contained a (valid) representation of 0.0 or

some invalid numerical string.

Example

#include <stdlib.h>

long double x;

x = atold("5.5"); /* x = 5.5 */

Documented Library Functions

1-122 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

See Also

atoi, atol, atoll, strtold

CrossCore Embedded Studio 1.1 1-123

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

atoll

Convert string to long long integer

Synopsis

#include <stdlib.h>

long long atoll (const char *nptr);

Description

The atoll function converts a character string to a long long integer value.

The character string to be converted is pointed to by the input pointer,

nptr. The function clears any leading characters for which

isspace would return true. Conversion begins at the first digit (with an

optional preceding sign) and terminates at the first non-digit.

There is no way to determine if a zero is a valid result or an indica-

tor of an invalid string.

Error Conditions

The atoll function returns 0 if no conversion can be made.

Example

#include <stdlib.h>

long long i;

i = atoll ("150000000000000"); /* i = 150000000000000LL */

See Also

atof, atoi, atol, strtod, strtol, strtoll, strtoul, strtoull

Documented Library Functions

1-124 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

avg

Mean of two values

Synopsis

#include <stdlib.h>

int avg (int x, int y);

Description

The avg function is an Analog Devices extension to the ANSI standard.

The avg function adds two arguments and divides the result by two. The

avg function is a built-in function which is implemented with an

Rn=(Rx+Ry)/2 instruction.

Error Conditions

None.

Example

#include <stdlib.h>

int i;

i = avg (10, 8); /* returns 9 */

See Also

lavg, llavg

CrossCore Embedded Studio 1.1 1-125

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

bitsfx

Bitwise fixed-point to integer conversion

Synopsis

#include <stdfix.h>

int_hr_t bitshr(short fract f);

int_r_t bitsr(fract f);

int_lr_t bitslr(long fract f);

uint_uhr_t bitsuhr(unsigned short fract f);

uint_ur_t bitsur(unsigned fract f);

uint_ulr_t bitsulr(unsigned long fract f);

Description

Given a fixed-point operand, the bitsfx family of functions return the

fixed-point value multiplied by 2F, where F is the number of fractional

bits in the fixed-point type. This is equivalent to the bit-pattern of the

fixed-point value held in an integer type.

Error Conditions

None.

Example

#include <stdfix.h>

uint_ulr_t ulr;

ulr = bitsulr(0.125ulr); /* ulr == 0x20000000 */

See Also

fxbits

Documented Library Functions

1-126 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

bsearch

Perform binary search in a sorted array

Synopsis

#include <stdlib.h>

void *bsearch (const void *key, const void *base,

size_t nelem, size_t size,

int (*compare)(const void *, const void *));

Description

The bsearch function searches the array base for an array element that

matches the element key. The size of each array element is specified by

size, and the array is defined to have nelem array elements.

The bsearch function will call the function compare with two arguments;

the first argument will point to the array element key and the second argu-

ment will point to an element of the array. The compare function should

return an integer that is either zero, or less than zero, or greater than zero,

depending upon whether the array element key is equal to, less than, or

greater than the array element pointed to by the second argument.

If the comparison function returns a zero, then bsearch will return a

pointer to the matching array element; if there is more than one matching

elements then it is not defined which element is returned. If no match is

found in the array, bsearch will return NULL.

The array to be searched would normally be sorted according to the crite-

ria used by the comparison function (the qsort function may be used to

first sort the array if necessary).

CrossCore Embedded Studio 1.1 1-127

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

Error Conditions

The bsearch function returns a null pointer when the key is not found in

the array.

Example

#include <stdlib.h>

#include <string.h>

#define SIZE 3

struct record_t {

char *name;

char *street;

char *city;

};

struct record_t data_base[SIZE] = {

{"Baby Doe" , "Central Park" , "New York"},

{"Jane Doe" , "Regents Park" , "London" },

{"John Doe" , "Queens Park" , "Sydney" }

};

static int

compare_function (const void *arg1, const void *arg2)

{

const struct record_t *pkey = arg1;

const struct record_t *pbase = arg2;

return strcmp (pkey->name,pbase->name);

}

struct record_t key = {"Baby Doe" , "" , ""};

struct record_t *search_result;

search_result = bsearch (&key,

data_base,

SIZE,

sizeof(struct record_t),

compare_function);

Documented Library Functions

1-128 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

See Also

qsort

CrossCore Embedded Studio 1.1 1-129

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

calloc

Allocate and initialize memory

Synopsis

#include <stdlib.h>

void *calloc (size_t nmemb, size_t size);

Description

The calloc function dynamically allocates a range of memory and initial-

izes all locations to zero. The number of elements (the first argument)

multiplied by the size of each element (the second argument) is the total

memory allocated. The memory may be deallocated with the free

function.

The object is allocated from the current heap, which is the default heap

unless heap_switch has been called to change the current heap to an alter-

nate heap.

Error Conditions

The calloc function returns a null pointer if unable to allocate the

requested memory.

Example

#include <stdlib.h>

int *ptr;

ptr = (int *) calloc (10, sizeof (int));

/* ptr points to a zeroed array of length 10 */

Documented Library Functions

1-130 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

See Also

free, heap_calloc, heap_free, heap_malloc, heap_realloc, malloc, realloc

CrossCore Embedded Studio 1.1 1-131

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

ceil

Ceiling

Synopsis

#include <math.h>

float ceilf (float x);

double ceil (double x);

long double ceild (long double x);

Description

The ceiling functions return the smallest integral value that is not less than

the argument x.

Error Conditions

None.

Example

#include <math.h>

double y;

float x;

y = ceil (1.05); /* y = 2.0 */

x = ceilf (-1.05); /* y = -1.0 */

See Also

floor

Documented Library Functions

1-132 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

clearerr

Clear file or stream error indicator

Synopsis

#include <stdio.h>

void clearerr(FILE *stream);

Description

The clearerr function clears the error and end-of-file (EOF) indicators for

the particular stream pointed to by stream.

The stream error indicators record whether any read or write errors have

occurred on the associated stream. The EOF indicator records when there is

no more data in the file.

Error Conditions

None.

Example

#include <stdio.h>

FILE *routine(char *filename)

{

FILE *fp;

fp = fopen(filename, "r");

/* Some operations using the file */

/* now clear the error indicators for the stream */

clearerr(fp);

return fp;

}

CrossCore Embedded Studio 1.1 1-133

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

See Also

feof, ferror

Documented Library Functions

1-134 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

clip

Clip

Synopsis

#include <stdlib.h>

int clip (int value1, int value2);

Description

The clip function is an Analog Devices extension to the ANSI standard.

The clip function returns its first argument if its absolute value is less than

the absolute value of its second argument, otherwise it returns the absolute

value of its second argument if the first is positive, or minus the absolute

value if the first argument is negative. The clip function is a built-in func-

tion which is implemented with an Rn = CLIP Rx BY Ry instruction.

Error Conditions

None.

Example

#include <stdlib.h>

int i;

i = clip (10, 8); /* returns 8 */

i = clip (8, 10); /* returns 8 */

i = clip (-10, 8); /* returns -8 */

See Also

fclip, lclip, llclip

CrossCore Embedded Studio 1.1 1-135

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

clock

Processor time

Synopsis

#include <time.h>

clock_t clock(void);

Description

The clock function returns the number of processor cycles that have

elapsed since an arbitrary starting point. The function returns the value

(clock_t) -1, if the processor time is not available or if it cannot be rep-

resented. The result returned by the function may be used to calculate the

processor time in seconds by dividing it by the macro CLOCKS_PER_SEC.

For more information, see time.h. An alternative method of measuring the

performance of an application is described in Measuring Cycle Counts.

Error Conditions

None.

Example

#include <time.h>

time_t start_time,stop_time;

double time_used;

start_time = clock();

compute();

stop_time = clock();

time_used = ((double) (stop_time - start_time)) / CLOCKS_PER_SEC;

Documented Library Functions

1-136 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

See Also

No related functions.

CrossCore Embedded Studio 1.1 1-137

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

cos

Cosine

Synopsis

#include <math.h>

float cosf (float x);

double cos (double x);

long double cosd (long double x);

Description

The cosine functions return the cosine of the first argument. The input is

interpreted as radians; the output is in the range [-1, 1].

Error Conditions

The input argument x for cosf must be in the domain [-1.647e6,

1.647e6] and the input argument for cosd must be in the domain

[-8.433e8, 8.433e8]. The functions return zero if x is outside their

domain.

Example

#include <math.h>

double y;

float x;

y = cos (3.14159); /* y = -1.0 */

x = cosf (3.14159); /* x = -1.0 */

See Also

acos, sin

Documented Library Functions

1-138 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

cosh

Hyperbolic cosine

Synopsis

#include <math.h>

float coshf (float x);

double cosh (double x);

long double coshd (long double x);

Description

The hyperbolic cosine functions return the hyperbolic cosine of their

argument.

Error Conditions

The domain of coshf is [-89.39, 89.39], and the domain for coshd is

[-710.44, 710.44]. The functions return HUGE_VAL if the input argument x

is outside the respective domains.

Example

#include <math.h>

float x;

double y;

x = coshf ( 1.0); /* x = 1.54308 */

y = cosh (-1.0); /* y = 1.54308 */

See Also

sinh

CrossCore Embedded Studio 1.1 1-139

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

count_ones

Count one bits in word

Synopsis

#include <stdlib.h>

int count_ones (int value);

Description

The count_ones function is an Analog Devices extension to the ANSI

standard.

The count_ones function returns the number of one bits in its argument.

Error Conditions

None.

Example

#include <stdlib.h>

int flags1 = 0xAD1;

int flags2 = -1;

int cnt1;

int cnt2;

cnt1 = count_ones (flags1); /* returns 6 */

cnt2 = count_ones (flags2); /* returns 32 */

See Also

lcount_ones, llcount_ones

Documented Library Functions

1-140 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

countlsfx

Count leading sign or zero bits

Synopsis

#include <stdfix.h>

int countlshr(short fract f);

int countlsr(fract f);

int countlslr(long fract f);

int countlsuhr(unsigned short fract f);

int countlsur(unsigned fract f);

int countlsulr(unsigned long fract f);

Description

Given a fixed-point operand x, the countlsfx family of functions return

the largest value of n for which x << n does not overflow. For a zero input

value, the function will return the number of bits in the fixed-point type.

In addition to the individually-named functions for each fixed-point type,

a type-generic macro countlsfx is defined for use in C99 mode. This may

be used with any of the fixed-point types.

Error Conditions

None.

Example

#include <stdfix.h>

int n;

n = countlsulr(0.125ulr); /* n == 2 */

n = countlsfx(0.125ulr); /* n == 2 */

CrossCore Embedded Studio 1.1 1-141

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

See Also

No related functions.

Documented Library Functions

1-142 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

ctime

Convert calendar time into a string

Synopsis

#include <time.h>

char *ctime(const time_t *t);

Description

The ctime function converts a calendar time, pointed to by the argument

t into a string that represents the local date and time. The form of the

string is the same as that generated by asctime, and so a call to ctime is

equivalent to

asctime(localtime(&t))

A pointer to the string is returned by ctime, and it may be overwritten by

a subsequent call to the function.

Error Conditions

None.

Example

#include <time.h>

#include <stdio.h>

time_t cal_time;

if (cal_time != (time_t)-1)

printf("Date and Time is %s",ctime(&cal_time));

CrossCore Embedded Studio 1.1 1-143

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

See Also

asctime, gmtime, localtime, time

Documented Library Functions

1-144 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

difftime

Difference between two calendar times

Synopsis

#include <time.h>

double difftime(time_t t1, time_t t0);

Description

The difftime function returns the difference in seconds between two cal-

endar times, expressed as a double. By default, the double data type

represents a 32-bit, single precision, floating-point, value. This form is

normally insufficient to preserve all of the bits associated with the differ-

ence between two calendar times, particularly if the difference represents

more than 97 days. It is recommended therefore that any function that

calls difftime is compiled with the -double-size-64 switch.

Error Conditions

None.

Example

#include <time.h>

#include <stdio.h>

#define NA ((time_t)(-1))

time_t cal_time1;

time_t cal_time2;

double time_diff;

CrossCore Embedded Studio 1.1 1-145

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

if ((cal_time1 == NA) || (cal_time2 == NA))

printf("calendar time difference is not available\n");

else

time_diff = difftime(cal_time2,cal_time1);

See Also

time

Documented Library Functions

1-146 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

div

Division

Synopsis

#include <stdlib.h>

div_t div (int numer, int denom);

Description

The div function divides numer by denom, both of type int, and returns a

structure of type div_t. The type div_t is defined as:

typedef struct {

int quot;

int rem;

} div_t;

where quot is the quotient of the division and rem is the remainder, such

that if result is of type div_t, then

result.quot * denom + result.rem == numer

Error Conditions

If denom is zero, the behavior of the div function is undefined.

Example

#include <stdlib.h>

div_t result;

result = div (5, 2); /* result.quot = 2, result.rem = 1 */

CrossCore Embedded Studio 1.1 1-147

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

See Also

divifx, fmod, fxdivi, idivfx, ldiv, lldiv, modf

Documented Library Functions

1-148 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

divifx

Division of integer by fixed-point to give integer result

Synopsis

#include <stdfix.h>

int divir(int numer, fract denom);

long int divilr(long int numer, long fract denom);

unsigned int diviur(unsigned int numer, unsigned fract denom);

unsigned long int diviulr(unsigned long int numer,

unsigned long fract denom);

Description

Given an integer numerator and a fixed-point denominator, the divifx

family of functions computes the quotient and returns the closest integer

value to the result.

Error Conditions

The divifx function has undefined behavior if the denominator is zero.

Example

#include <stdfix.h>

unsigned long int ulquo;

ulquo = diviulr(125, 0.125ulr); /* ulquo == 1000 */

See Also

div, fxdivi, idivfx, ldiv, lldiv

CrossCore Embedded Studio 1.1 1-149

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

dyn_AddHeap

Specify a new region of target memory which may be used for relocated,

dynamically-loaded code and data

Synopsis

#include <libdyn.h>

DYN_RESULT dyn_AddHeap(dyn_mem_image *image,

dyn_heap *heap);

Description

The dyn_AddHeap function declares a new region of target memory that

may be used to relocate the code or data in dynamically-loadable module

(DLM) image, as previously validated by dyn_ValidateImage. The heap

parameter indicates the width and alignment of the memory, as well as the

start and size.

The heap parameter must point to a dyn_heap structure that has been ini-

tialized by dyn_heap_init.

Error Conditions

The dyn_AddHeap function returns a status value indicating success, or

the reason for failure, as follows.

Returned Value Reason

DYN_NO_ERROR Success. The heap was added to the image’s list of regions

from which to allocate target memory.

DYN_BAD_PTR Either image or heap was NULL.

DYN_BAD_WIDTH A heap has already been specified which has the same width

as the heap being added.

Documented Library Functions

1-150 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

Example

#include <libdyn.h>

DYN_RESULT data_heap(dyn_mem_image *image) {,

static int myspace[50];

static dyn_heap h[1];

dyn_heap_init(h, myspace, sizeof(myspace), 4, 2);

/* error-checking omitted */

return dyn_AddHeap(image, h);

}

See Also

dyn_ValidateImage, dyn_heap_init, dyn_SetSectionAddr, dyn_FreeSec-

tionMem, dyn_AllocSectionMemHeap, malloc

CrossCore Embedded Studio 1.1 1-151

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

dyn_alloc

Allocate space from a target heap

Synopsis

#include <libdyn.h>

DYN_RESULT dyn_alloc(dyn_heap *heap,

size_t naddrs,

void **ptr);

Description

The dyn_alloc function allocates a number of contiguous addressable loca-

tions from the target heap specified by the heap parameter. The first of

these allocated locations is returned as the address pointed-to by the ptr

parameter. The naddrs parameter indicates how many contiguous loca-

tions must be allocated.

This function is not normally called directly; it is used by dyn_AllocSec-

tionMem and dyn_AllocSectionMemHeap.

Error Conditions

The dyn_alloc function returns a status value indicating success, or the

reason for failure, as follows.

Returned Value Reason

DYN_NO_ERROR Success. The space was allocated.

DYN_BAD_PTR Either ptr or heap was NULL.

DYN_BAD_IMAGE The available space in the heap is not aligned according to

the heap’s alignment. This should never occur.

DYN_TOO_SMALL There is insufficient space left in the heap to allocate naddrs

locations in an aligned manner.

Documented Library Functions

1-152 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

Example

#include <libdyn.h>

void *get_space(dyn_heap *heap) {

void *ptr = 0;

if (dyn_alloc(heap, 100, &ptr) == DYN_NO_ERROR)

return ptr;

return 0;

}

See Also

dyn_ValidateImage, dyn_heap_init, dyn_AddHeap, dyn_Relocate, dyn_-

FreeSectionMem, dyn_AllocSectionMemHeap, malloc

CrossCore Embedded Studio 1.1 1-153

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

dyn_AllocSectionMem

Allocate target memory aligned for a section in a dynamically-loadable

module

Synopsis

#include <libdyn.h>

DYN_RESULT dyn_AllocSectionMem(dyn_mem_image *image,

dyn_section *sections,

size_t secnum,

dyn_section_mem **mem);

Description

The dyn_AllocSectionMem function allocates a target memory buffer

large enough to hold the contents of section secnum, in dynamically-load-

able module (DLM) image, as previously validated by dyn_ValidateImage.

The sections parameter is a local copy of the DLM’s section table,

obtained by dyn_GetSections. The memory allocated by this function

should be freed in a single step at a later time, by calling

dyn_FreeSectionMem.

Two areas of memory are allocated by this function:

1. A space is allocated in target memory to hold the contents of the

section. This space is allocated by dyn_alloc from a heap defined

by dyn_AddHeap; the heap in question is selected on the basis of the

memory width of the section secnum, by the dyn_GetHeapForWidth

function.

2. A space is allocated in local memory to keep track of this alloca-

tion. This memory is allocated from the default heap, and is

attached to image, so that it may be freed later.

On exit, *mem points to the second of the two allocations.

Documented Library Functions

1-154 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

Error Conditions

The dyn_AllocSectionMem function returns a status value indicating suc-

cess, or the reason for failure, as follows.

Example

#include <libdyn.h>

dyn_section_mem *secmem(dyn_mem_image *image,

dyn_section *sections,

int nsecs) {

int i;

dyn_section_mem *mem = 0;

for (i = 0; i < nsecs; i++) {

if (dyn_AllocSectionMem(image, sections, i, &mem) !=

DYN_NO_ERROR) {

return NULL;

}

return mem;

}

Returned Value Reason

DYN_NO_ERROR Success. *mem contains a pointer to a suitable block of

memory; mem->aligned_addr can be used by dyn_SetSec-

tionAddr for section secnum.

DYN_BAD_PTR One or more of the pointer parameters was NULL.

DYN_NO_MEM Malloc failed, when attempting to allocate sufficient mem-

ory.

DYN_BAD_IMAGE The secnum parameter does not refer to a valid section in

the DLM.

CrossCore Embedded Studio 1.1 1-155

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

See Also

dyn_AddHeap, dyn_ValidateImage, dyn_alloc, dyn_GetHeapForWidth,

dyn_Relocate, dyn_FreeSectionMem, dyn_AllocSectionMemHeap,

malloc

Documented Library Functions

1-156 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

dyn_AllocSectionMemHeap

Allocate memory from a given heap, aligned for a section in a dynami-

cally-loadable module

Synopsis

#include <libdyn.h>

DYN_RESULT dyn_AllocSectionMemHeap(dyn_mem_image *image,

dyn_section *sections,

size_t secnum,

dyn_section_mem **mem,

int heapidx);

Description

The dyn_AllocSectionMemHeap function allocates a target memory buf-

fer large enough to hold the contents of section secnum, in

dynamically-loadable module (DLM) image, as previously validated by

dyn_ValidateImage. The sections parameter is a local copy of the DLM’s

section table, obtained by dyn_GetSections. The memory allocated by

this function should be freed in a single step at a later time, by calling

dyn_FreeSectionMem. The heapidx parameter indicates which heap should

be used to allocate house-keeping space.

Two areas of memory are allocated by this function:

1. A space is allocated in target memory to hold the contents of the

section. This space is allocated by dyn_alloc from a heap defined

by dyn_AddHeap; the heap in question is selected on the basis of the

memory width of the section secnum by dyn_GetHeapForWidth.

2. A space is allocated in local memory to keep track of this alloca-

tion. This memory is allocated using heap_malloc, with the heap in

question specified by heapidx. The resulting memory is attached to

image, so that it may be freed later.

CrossCore Embedded Studio 1.1 1-157

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

On exit, *mem points to the second of the two allocations.

Error Conditions

The dyn_AllocSectionMemHeap function returns a status value indicat-

ing success, or the reason for failure, as follows.

Example

#include <libdyn.h>

dyn_section_mem *secmem(dyn_mem_image *image,

dyn_section *sections,

int nsecs) {

int i;

dyn_section_mem *mem = 0;

for (i = 0; i < nsecs; i++) {

if (dyn_AllocSectionMemHeap(image, sections, i, &mem, 0) !=

DYN_NO_ERROR)

return NULL;

}

return mem;

}

Returned Value Reason

DYN_NO_ERROR Success. *mem contains a pointer to a suitable block of

memory; mem->aligned_addr can be used by dyn_SetSec-

tionAddr for section secnum.

DYN_BAD_PTR One or more of the pointer parameters was NULL.

DYN_NO_MEM Malloc failed, when attempting to allocate sufficient mem-

ory.

DYN_BAD_IMAGE The secnum parameter does not refer to a valid section in

the DLM.

Documented Library Functions

1-158 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

See Also

dyn_AddHeap, dyn_ValidateImage, dyn_GetHeapForWidth, dyn_alloc,

dyn_Relocate, dyn_FreeSectionMem, dyn_AllocSectionMemHeap,

malloc

CrossCore Embedded Studio 1.1 1-159

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

dyn_CopySectionContents

Copy the sections of a valid dynamically-loadable module

Synopsis

#include <libdyn.h>

DYN_RESULT dyn_CopySectionContents(dyn_mem_image *image,

dyn_section *sections);

Description

The dyn_CopySectionContents function will copy the contents of all sec-

tions from a dynamically-loadable module (DLM), into

previously-allocated local space. image is a DLM previously validated by

dyn_ValidateImage, and sections is a local copy of the DLM’s section

table, obtained by dyn_GetSections. An address must have previously

been allocated to each section, by dyn_SetSectionAddr.

Error Conditions

The dyn_CopySectionContents function returns a status value indicating

success, or the reason for failure, as follows.

Returned Value Reason

DYN_NO_ERROR Success. The DLM section contents were copied.

DYN_BAD_PTR The sections or image parameter is NULL.

DYN_BAD_IMAGE The image does not have the right magic number, or offsets

within the image are nonsensical.

Documented Library Functions

1-160 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

Example

#include <libdyn.h>

int copy_dlm(dyn_mem_image *image, dyn_sections *secs) {

if (dyn_CopySectionContents(image, secs) == DYN_NO_ERROR)

return 0;

return -1;

}

See Also

dyn_ValidateImage, dyn_GetNumSections, dyn_GetSections, dyn_Get-

StringTableSize, dyn_GetStringTable, dyn_GetExpSymTab,

dyn_LookupByName, dyn_Relocate, dyn_SetSectionAddr,

dyn_AllocSectionMem

CrossCore Embedded Studio 1.1 1-161

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

dyn_FreeEntryPointArray

Release a previously-allocated list of entry points to the dynamically-load-

able module

Synopsis

#include <libdyn.h>

void dyn_FreeEntryPointArray(char *strtab, char **entries);

Description

The dyn_FreeEntryPointArray function releases memory that was allo-

cated by dyn_GetEntryPointArray.

Error Conditions

None.

Example

See dyn_GetEntryPointArray for an example.

See Also

dyn_ValidateImage, dyn_GetExpSymTab, dyn_LookupByName,

dyn_Relocate, dyn_GetEntryPointArray

Documented Library Functions

1-162 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

dyn_FreeSectionMem

Release memory allocated for sections in a dynamically-loadable module

Synopsis

#include <libdyn.h>

void dyn_FreeSectionMem(dyn_mem_image *image);

Description

The dyn_FreeSectionMem function releases house-keeping memory

blocks that were allocated by dyn_AllocSectionMem or dyn_AllocSection-

MemHeap. image is a DLM previously validated by dyn_ValidateImage.

Target memory, allocated from heaps declared by dyn_AddHeap, remains

valid.

Error Conditions

None.

Example

#include <libdyn.h>

void secmem(dyn_mem_image *image,dyn_section *sections ,int

nsecs) {

int i;

dyn_section_mem *mem = 0;

for (i = 0; i < nsecs; i++) {

if (dyn_AllocSectionMem(image, sections, i, &mem) !=

DYN_NO_ERROR)

return;

}

CrossCore Embedded Studio 1.1 1-163

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

do_something();

dyn_FreeSectionMem(image);

return;

}

See Also

dyn_ValidateImage, dyn_GetNumSections, dyn_GetSections, dyn_Get-

StringTableSize, dyn_GetStringTable, dyn_GetExpSymTab,

dyn_LookupByName, dyn_Relocate, dyn_SetSectionAddr, dyn_Copy-

SectionContents, dyn_AllocSectionMem

Documented Library Functions

1-164 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

dyn_GetEntryPointArray

Obtain a list of symbols exported by a dynamically-loadable module

Synopsis

#include <libdyn.h>

DYN_RESULT dyn_GetEntryPointArray(dyn_mem_image *image,

size_t symidx,

size_t stridx,

char **hstrtab,

char ***entries,

size_t *num_entries);

Description

The dyn_GetEntryPointArray function obtains the contents of the

exported symbol table of the dynamically-loadable module (DLM) image,

in an array of string pointers, pointed to by *entries. *num_entries is set

to contain the number of entries in the allocated array. Each entry in the

allocated array points to a string in a local copy of the string table, con-

verted to local string format. *entries is set to point to this local string

table.

This function can be used to determine which symbols are exported by the

DLM, if this is not known in advance. Once the array of entry-point

strings has been obtained, the strings can be passed to dyn_LookupByName

to determine the resolved address of the entry-point.

This function may only be called after the DLM has been relocated by

calling dyn_Relocate; prior to that point, the exported symbol table’s

entries are not completely resolved.

The symidx and stridx parameters identify the sections that contain the

exported symbol table and exported string table, respectively; these param-

eters are obtained via dyn_GetExpSymTab.

CrossCore Embedded Studio 1.1 1-165

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

The allocated memory should be freed by dyn_FreeEntryPointArray, once

it is no longer required.

Error Conditions

The dyn_GetEntryPointArray function returns a status value indicating

success, or the reason for failure, as follows.

Example

#include <stdio.h>

#include <libdyn.h>

void list_syms(dyn_mem_image *image,

const char *strtab,

dyn_section *sections) {

size_t symidx, stridx;

char *hstrtab, **syms;

int i, nsyms;

dyn_GetExpSymTab(image, symtab, sections, &symidx, &stridx);

dyn_GetEntryPointArray(image, symidx, stridx, &hstrtab, &nsyms,

&syms);

for (i = 0; i < nsyms; i++)

printf(“Sym %d is %s\n”, i, syms[i]);

dyn_FreeEntryPointArray(hstrtab, syms);

}

Returned Value Reason

DYN_NO_ERROR Success. *ptr contains the address of the symbol, in the relo-

cated image.

DYN_BAD_PTR One or more of the pointer parameters is NULL.

DYN_NO_MEM There was not enough space to allocate either the entry

array, or the local copy of the string table.

DYN_NOT_FOUND The sections for the exported string table or exported sym-

bol table could not be retrieved.

Documented Library Functions

1-166 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

See Also

dyn_ValidateImage, dyn_GetNumSections, dyn_GetSections, dyn_Get-

StringTableSize, dyn_GetStringTable, dyn_GetExpSymTab,

dyn_Relocate, dyn_SetSectionAddr, dyn_AllocSectionMem,

dyn_CopySectionContents

CrossCore Embedded Studio 1.1 1-167

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

dyn_GetExpSymTab

Locate a dynamically-loadable module’s table of exported symbols

Synopsis

#include <libdyn.h>

DYN_RESULT dyn_GetExpSymTab(dyn_mem_image *image,

const char *strtab,

dyn_section *sections,

size_t *symidx,

size_t *stridx);

Description

The dyn_GetExpSymTab function searches the dynamically-loadable

module (DLM) pointed to by image, looking for the table of exported

symbols. The strtab and sections parameters must be pointers to the

DLM’s string table and section table, obtained by dyn_GetStringTable

and dyn_GetSections, respectively.

The DLM’s exported-symbol table consists of two sections. One is a string

table, containing the names of exported symbols in native processor for-

mat; the other is a table where each entry points to the symbol’s name in

said string table, and to the symbol itself (whether code or data).

If successful, the function records the section numbers of the exported sec-

tion table and exported string table into the locations pointed to by

symidx and stridx, respectively.

Documented Library Functions

1-168 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

Error Conditions

The dyn_GetExpSymTab function returns a status value indicating suc-

cess, or the reason for failure, as follows.

Example

#include <libdyn.h>

static size_t sec_tab, str_tab;

int find_secs(dyn_mem_image *image,

const char strtab,

dyn_section *sections) {

if (dyn_GetExpSymTab(image, strtab, sections,

&sec_tab, &str_tab) == DYN_NO_ERROR)

return 0;

return -1;

}

See Also

dyn_ValidateImage, dyn_GetNumSections, dyn_GetSections, dyn_Get-

StringTableSize, dyn_GetStringTable, dyn_LookupByName,

dyn_Relocate, dyn_SetSectionAddr, dyn_AllocSectionMem,

dyn_CopySectionContents

Returned Value Reason

DYN_NO_ERROR Success. *symidx contains the section number containing

the exported symbol table, and *stridx contains the section

number containing the exported string table.

DYN_BAD_PTR One or more of the parameters is NULL.

DYN_BAD_IMAGE The function could not locate sections for both the

exported string table and the exported symbol table.

CrossCore Embedded Studio 1.1 1-169

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

dyn_GetHeapForWidth

Locate a target-memory heap that has the right number of bits per

addressable unit.

Synopsis

#include <libdyn.h>

DYN_RESULT dyn_GetHeapForWidth(dyn_mem_image *image,

size_t byte_width,

dyn_heap **heap);

Description

The dyn_GetHeapForWidth function searches all target-memory heaps

that have been declared for this image (using the dyn_AddHeap function),

and returns the one that has a width of byte_width via *heap, if there is

one.

Error Conditions

The dyn_GetHeapForWidth function returns a status value indicating

success, or the reason for failure, as follows.

Returned Value Reason

DYN_NO_ERROR Success. *heap contains a pointer to a heap which may be

used for allocation.

DYN_BAD_PTR Either heap or image was NULL.

DYN_NOT_FOUND No heap has been attached to image using dyn_AddHeap(),

which has a width that matches byte_width.

Documented Library Functions

1-170 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

Example

#include <libdyn.h>

dyn_heap *fetch_heap(dyn_mem_image *image, size_t width) {

dyn_heap *heap = 0;

if (dyn_GetHeapForWidth(image, &heap) != DYN_NO_ERROR)

return NULL;

return heap;

}

See Also

dyn_AddHeap, dyn_ValidateImage, dyn_heap_init, dyn_alloc, dyn_Free-

SectionMem, dyn_AllocSectionMemHeap, malloc

CrossCore Embedded Studio 1.1 1-171

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

dyn_GetNumSections

Obtain the number of sections in a dynamically-loadable module

Synopsis

#include <libdyn.h>

DYN_RESULT dyn_GetNumSections(dyn_mem_image *image,

size_t *num_sections);

Description

The dyn_GetNumSections function returns the number of sections in a

validate dynamically-loadable module (DLM), as produced by elf2dyn.

The image parameter should have been populated by a previous call to

dyn_ValidateImage.

In the context of this function, “sections” means “portions of the DLM

that contain executable code or usable data”; it does not include the string

table or any relocations for the DLM.

Upon success, the function writes the number of sections to the location

pointed to by the num_sections parameter.

Error Conditions

The dyn_GetNumSections function returns a status value indicating suc-

cess, or the reason for failure, as follows.

Returned Value Reason

DYN_NO_ERROR Success. *num_sections will contain the section count.

DYN_BAD_PTR The image or num_sections parameter is NULL.

Documented Library Functions

1-172 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

Example

#include <stdio.h>

#include <libdyn.h>

void count_sections(dyn_mem_image *dlm_info) {

size_t nsec;

if (dyn_GetNumSections(dlm_info, &nsec) == DYN_NO_ERROR)

printf(“There are %d section\n”, nsec);

}

See Also

dyn_ValidateImage, dyn_GetSections, dyn_GetStringTableSize,

dyn_GetStringTable, dyn_GetExpSymTab, dyn_LookupByName,

dyn_Relocate, dyn_SetSectionAddr, dyn_AllocSectionMem,

dyn_CopySectionContents

CrossCore Embedded Studio 1.1 1-173

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

dyn_GetSections

Obtain a native copy of the section table from a valid dynamically-load-

able module.

Synopsis

#include <libdyn.h>

DYN_RESULT dyn_GetSections(dyn_mem_image *image,

dyn_section *sections);

Description

The dyn_GetSections function accepts a pointer sections to a block of

memory, and populates it with a native copy of the section table from the

dynamically-loadable module (DLM) pointed to by image. The resulting

section table copy is in the native byte order of the target processor.

The memory buffer must have been allocated previously, and must be

large enough to contain all the section headers for the DLM.

Error Conditions

The dyn_GetSections function returns a status value indicating success, or

the reason for failure, as follows.

Returned Value Reason

DYN_NO_ERROR Success. The section table will copied to sections.

DYN_BAD_PTR The sections or image parameter is NULL.

Documented Library Functions

1-174 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

Example

#include <stdlib.h>

#include <libdyn.h>

char *get_sec_table(dyn_mem_image *image, int nsecs) {

char *space = malloc(nsecs * sizeof(dyn_section));

if (dyn_GetSections(image, space) == DYN_NO_ERROR)

return space;

return NULL;

}

See Also

dyn_ValidateImage, dyn_GetNumSections, dyn_GetStringTableSize,

dyn_GetStringTable, dyn_GetExpSymTab, dyn_LookupByName,

dyn_Relocate, dyn_SetSectionAddr, dyn_AllocSectionMem,

dyn_CopySectionContents

CrossCore Embedded Studio 1.1 1-175

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

dyn_GetStringTable

Obtain a native copy of the string table of a valid dynamically-loadable

module

Synopsis

#include <libdyn.h>

DYN_RESULT dyn_GetStringTable(dyn_mem_image *image,

char *buffer);

Description

The dyn_GetStringTable function copies the string table from the dynam-

ically-loadable module image to the space pointed to by buffer. The

resulting copy is in the native format of the target processor.

Error Conditions

The dyn_GetStringTable function returns a status value indicating suc-

cess, or the reason for failure, as follows.

Returned Value Reason

DYN_NO_ERROR Success. buffer contains a native copy of the string table

(one character per location).

DYN_BAD_PTR The buffer or image parameter is NULL.

Documented Library Functions

1-176 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

Example

#include <stdlib.h>

#include <libdyn.h>

char *get_strtab(dyn_mem_image *dlm_info, size_t *nchars) {

char *ptr = malloc(nchars);

if (dyn_GetStringTable(dlm_info, ptr) == DYN_NO_ERROR)

return ptr;

return NULL;

}

See Also

dyn_ValidateImage, dyn_GetNumSections, dyn_GetSections, dyn_Get-

StringTableSize, dyn_GetExpSymTab, dyn_LookupByName,

dyn_Relocate, dyn_SetSectionAddr, dyn_AllocSectionMem,

dyn_CopySectionContents

CrossCore Embedded Studio 1.1 1-177

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

dyn_GetStringTableSize

Get the size of the string table in a valid dynamically-loadable module

Synopsis

#include <libdyn.h>

DYN_RESULT dyn_GetStringTableSize(dyn_mem_image *image,

size_t *sz);

Description

The dyn_GetStringTableSize function returns the number of bytes

required to hold the string table for the dynamically-loadable module

(DLM) pointed to by image. The size is returned in the location pointed

to by the sz parameter.

In a dynamically-loadable module, the string table contains the names of

the various sections in the DLM. It does not contain character strings or

other data that constitutes the loadable part of the DLM.

Error Conditions

The dyn_GetStringTableSize function returns a status value indicating

success, or the reason for failure, as follows.

Returned Value Reason

DYN_NO_ERROR Success. *sz contains the size of the string table.

DYN_BAD_PTR The sz or image parameter is NULL.

Documented Library Functions

1-178 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

Example

#include <stdio.h>

#include <libdyn.h>

void get_strtab_size(dyn_mem_image *dlm_info) {

size_t nchars;

if (dyn_GetStringTableSize(dlm_info, &nchars) == DYN_NO_ERROR)

printf(“There are %d characters in the table\n”, nchars);

}

See Also

dyn_ValidateImage, dyn_GetNumSections, dyn_GetSections, dyn_Get-

StringTable, dyn_GetExpSymTab, dyn_LookupByName, dyn_Relocate,

dyn_SetSectionAddr, dyn_AllocSectionMem, dyn_CopySectionContents

CrossCore Embedded Studio 1.1 1-179

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

dyn_heap_init

Initialize a target heap for dynamically-loadable modules

Synopsis

#include <libdyn.h>

DYN_RESULT dyn_heap_init(dyn_heap *heap,

void *base,

size_t size,

size_t width,

size_t align);

Description

The dyn_heap_init function initializes the heap parameter, so that it con-

tains a description of a region of target memory that can be used to

relocate dynamically-loaded code or data. The resulting structure will be

suitable for passing to dyn_AddHeap.

The heap parameter must point to a dyn_heap structure that is initialized

as follows:

•base – the address of the first addressable unit in the region of tar-

get memory.

•size – the number of addressable units that can be allocated.

Therefore, this should be set to the same value as total_size.

•width – should be set to the number of 8-bit values that can fit into

a single location in the target memory. Therefore: 2 for VISA

space, 4 for normal data memory, 6 for program memory, and 8 for

long-word data memory. Note that only one heap may be specified,

for each given width.

Documented Library Functions

1-180 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

•align – when memory is allocated from this region, the offset into

the region will be a multiple of this value. Therefore, this must be

1, 2 or 4, as required for memory alignment.

Error Conditions

The dyn_heap_init function returns a status value indicating success, or

the reason for failure, as follows.

Example

#include <libdyn.h>

DYN_RESULT data_heap(dyn_heap *heap) {,

static int myspace[50];

return dyn_heap_init(heap, myspace, sizeof(myspace), 4, 2);

}

See Also

dyn_ValidateImage, dyn_GetNumSections, dyn_GetSections, dyn_Get-

StringTableSize, dyn_GetStringTable, dyn_GetExpSymTab,

dyn_LookupByName, dyn_Relocate, dyn_SetSectionAddr, dyn_Copy-

SectionContents, dyn_FreeSectionMem, dyn_AllocSectionMemHeap,

malloc

Returned Value Reason

DYN_NO_ERROR Success. The dyn_heap structure is now initialized.

DYN_BAD_PTR Either image or heap was NULL, or size was zero.

DYN_BAD_IMAGE The base pointer was not appropriately aligned for the align

parameter.

CrossCore Embedded Studio 1.1 1-181

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

dyn_LookupByName

Locate an exported symbol in a dynamically-loadable module

Synopsis

#include <libdyn.h>

DYN_RESULT dyn_LookupByName(dyn_mem_image *image,

const char *name,

void *symtab,

uint32_t secsize,

void **ptr);

Description

The dyn_LookupByName function searches the exported symbol table of

the dynamically-loadable module (DLM) image, looking for a symbol

called name. If such a symbol is found, the symbol’s address is returned in

the location pointed to by ptr. symtab is a pointer to the contents of the

DLM’s exported symbol table, as previously located via dyn_GetExpSym-

Tab; secsize indicates the section’s size.

This function may only be called after the DLM has been relocated by

calling dyn_Relocate; prior to that point, the exported symbol table’s

entries are not completely resolved.

The name parameter must match the exported symbol exactly. This means

that it must also be mangled appropriately for the symbol’s namespace.

Documented Library Functions

1-182 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

Error Conditions

The dyn_LookupByName function returns a status value indicating suc-

cess, or the reason for failure, as follows.

Example

#include <stdio.h>

#include <libdyn.h>

int call_fn(dyn_mem_image *image,

void *symtab,

uint32_t secsize,

const char *fnname) {

void *ptr;

if (dyn_LookupByName(image, fnname, symtab,

secsize, &ptr) == DYN_NO_ERROR) {

int (*fnptr)(void) = (int (*)(void))ptr;

return (*fnptr)();

}

return -1;

}

Returned Value Reason

DYN_NO_ERROR Success. *ptr contains the address of the symbol, in the relo-

cated image.

DYN_BAD_PTR The ptr or image parameter is NULL.

DYN_NOT_FOUND The exported symbol table does not contain a symbol

whose name exactly matches name.

CrossCore Embedded Studio 1.1 1-183

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

See Also

dyn_ValidateImage, dyn_GetNumSections, dyn_GetSections, dyn_Get-

StringTableSize, dyn_GetStringTable, dyn_GetExpSymTab,

dyn_Relocate, dyn_SetSectionAddr, dyn_AllocSectionMem,

dyn_CopySectionContents

Documented Library Functions

1-184 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

dyn_RecordRelocOutOfRange

Record which relocation cannot be completed, while relocating a dynami-

cally-loadable module

Synopsis

#include <libdyn.h>

int dyn_RecordRelocOutOfRange(void *ref_addr,

uint32_t sym_addr);

Description

The dyn_RecordRelocOutOfRange function is invoked by dyn_Relocate,

if a computed relocation is out of range. It provides an opportunity to

make a note of the offending reference. Alternatively, it provides an

opportunity to ignore the problem.

ref_addr is the target address of the location being relocated, while

sym_addr is the computed location or value which is being referenced by

ref_addr. sym_addr is presented before being manipulated to fit into the

field at ref_addr. For example, if ref_addr only references even addresses,

the stored value in the field might be shifted down one place; sym_addr

represents the value before this shift has happened.

The default implementation of the dynRecordRelocOutOfRange function

records both ref_addr and sym_addr, so that they can be retrieved later

using dyn_RetrieveRelocOutOfRange.

Error Conditions

The dyn_RecordRelocOutOfRange function must return a value indicat-

ing whether this combination of ref_addr and sym_addr should be

considered an error. If the function returns false, then dyn_Relocate will

continue its operation. If the function returns true, then dyn_Relocate

will abort.

CrossCore Embedded Studio 1.1 1-185

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

Example

#include <libdyn.h>

int dyn_RecordRelocOutOfRange(void *ref_addr, uint32_t sym_addr)

{

/* alternative implementation that ignores all errors */

return 0;

}

See Also

dyn_Relocate, dyn_RetrieveRelocOutOfRange

Documented Library Functions

1-186 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

dyn_Relocate

Relocate a dynamically-loadable module

Synopsis

#include <libdyn.h>

DYN_RESULT dyn_Relocate(dyn_mem_image *image,

dyn_section *sections);

Description

The dyn_Relocate function processes the relocations in a dynami-

cally-loadable module (DLM) once its sections have been copied into local

memory.

image is the DLM, as loaded and validated. sections is a copy of the

DLM’s section table, as obtained via dyn_GetSections. Before relocation

can be performed, space must have been allocated for each of the sections

in the file, using dyn_AllocSectionMem, and the sections’ contents copied

into that space using dyn_CopySectionContents.

Error Conditions

The dyn_Relocate function returns a status value indicating success, or the

reason for failure, as follows.

Returned Value Reason

DYN_NO_ERROR Success. All sections were relocated.

DYN_BAD_PTR The sections or image parameter is NULL.

DYN_NO_SECTION_ADDR There is a section in the DLM which has not had an address

allocated, prior to attempting to relocate it.

DYN_BAD_RELOC The DLM contains a relocation that is not recognized by

the current instance of libdyn.

CrossCore Embedded Studio 1.1 1-187

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

Example

#include <libdyn.h>

int reloc_dlm(dyn_mem_image *dlm_info, dyn_section *sections) {

if (dyn_Relocate(dlm_info, sections) == DYN_NO_ERROR)

return 0;

return -1;

}

See Also

dyn_ValidateImage, dyn_GetNumSections, dyn_GetSections, dyn_Get-

StringTableSize, dyn_GetStringTable, dyn_GetExpSymTab,

dyn_LookupByName, dyn_SetSectionAddr, dyn_AllocSectionMem,

dyn_CopySectionContents, dyn_RecordRelocOutOfRange,

dyn_RetrieveRelocOutOfRange

DYN_BAD_WIDTH The DLM contains a relocation that references a section

with a word size not supported by this instance of libdyn.

DYN_NOT_ALIGNED The DLM could not complete relocations because there is a

section that is not appropriately aligned for its word size.

DYN_OUT_OF_RANGE The DLM could not apply a relocation because the com-

puted value does not fit into the available space. This gener-

ally means that the reference and the target of the relocation

are too far apart. The function will invoke dyn_RecordRe-

locOutOfRange to record the details of the failing reloca-

tion. These details can be retrieved with

dyn_RetrieveRelocOutOfRange.

Returned Value Reason

Documented Library Functions

1-188 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

dyn_RetrieveRelocOutOfRange

Retrieve information about a relocation that failed

Synopsis

#include <libdyn.h>

DYN_RESULT dyn_RetrieveRelocOutOfRange(void **ref_addr,

uint32_t *sym_addr);

Description

The dyn_RetrieveRelocOutOfRange function is used to retrieve informa-

tion about a failing relocation, if dyn_Relocate returns DYN_OUT_OF_RANGE.

The information must first have been saved by

dyn_RecordRelocOutOfRange.

*ref_addr will be set to the target address of the location that was being

relocated, while *sym_addr will be set to the computed location or value

that was being referenced by *ref_addr.

Error Conditions

The dyn_RetrieveRelocOutOfRange function returns a value to indicate

the status of its operation, as follows.

Returned Value Reason

DYN_NO_ERROR Success. *ref_addr and *sym_addr have been updated.

DYN_BAD_PTR Either ref_addr or sym_addr was NULL.

CrossCore Embedded Studio 1.1 1-189

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

Example

#include <libdyn.h>

void reloc_dlm(dyn_mem_image *dlm_info, dyn_section *sections) {

if (dyn_Relocate(dlm_info, sections) == DYN_OUT_OF_RANGE &&

dyn_RetrieveRelocOutOfRange(&ref, &sym) == DYN_NO_ERROR)

printf(“Relocation %p -> %p failed\n”, ref, sym);

}

See Also

dyn_Relocate, dyn_RecordRelocOutOfRange

Documented Library Functions

1-190 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

dyn_RewriteImageToFile

Write a dynamically-loadable module back to a file, after relocation

Synopsis

#include <libdyn.h>

DYN_RESULT dyn_RewriteImageToFile(dyn_mem_image *image,

dyn_section *sections,

size_t num_sections,

FILE *outf);

Description

The dyn_RewriteImageToFile function writes the contents of a dynami-

cally-loadable module (DLM) to the specified output stream outf, after

relocation has taken place.

image is the DLM, as loaded, validated and relocated. sections is a copy

of the DLM’s section table, as obtained via dyn_GetSections.

Error Conditions

The dyn_RewriteImageToFile function returns a status value indicating

success, or the reason for failure, as follows.

Returned Value Reason

DYN_NO_ERROR Success. All sections were written back to the output stream

without error.

DYN_BAD_WRITE One of the output operations on the output stream did not

succeed.

DYN_NO_MEM There was insufficient memory to obtain a local working

copy of some data.

CrossCore Embedded Studio 1.1 1-191

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

Example

#include <libdyn.h>

int reloc_dlm(dyn_mem_image *dlm,

dyn_section *secs,

size_t nsecs,

FILE *fp) {

if (dyn_Relocate(dlm, secs) == DYN_NO_ERROR &&

dyn_RewriteImageToFile(dlm, secs, nsecs, fp) ==

DYN_NO_ERROR)

return 0;

return -1;

}

See Also

dyn_ValidateImage, dyn_GetNumSections, dyn_GetSections, dyn_Get-

StringTableSize, dyn_GetStringTable, dyn_GetExpSymTab,

dyn_LookupByName, dyn_SetSectionAddr, dyn_AllocSectionMem,

dyn_CopySectionContents

DYN_BAD_PTR The image parameter was NULL, or a there is a corrupt

internal memory reference.

DYN_NOT_FOUND Not all sections could be located, suggesting that the num_-

sections parameter is incorrect.

Returned Value Reason

Documented Library Functions

1-192 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

dyn_SetSectionAddr

Set the local address for a section in a dynamically-loadable module

Synopsis

#include <libdyn.h>

DYN_RESULT dyn_SetSectionAddr(dyn_mem_image *image,

dyn_section *sections,

size_t secnum,

void *addr);

Description

The dyn_SetSectionAddr function sets the local address for a given section

within a dynamically-loadable module (DLM). image is the DLM, vali-

dated by dyn_ValidateImage. sections is a native copy of the DLM’s

section table, obtained by dyn_GetSections. secnum is the number for the

section for which to set the address. addr is the local address.

In this context, “setting the address” means informing the DLM that

address addr is a suitable address at which section secnum may reside after

relocation; if dyn_CopySectionContents is called, the section’s contents

will be copied to addr, so sufficient space must have previously been

reserved at that address.

CrossCore Embedded Studio 1.1 1-193

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

Error Conditions

The dyn_SetSectionAddr function returns a status value indicating suc-

cess, or the reason for failure, as follows.

Example

#include <libdyn.h>

int set_addr(dyn_mem_image *image, dyn_section *secs,

size_t num, void *ptr) {

if (dyn_SetSectionAddr(image, secs, num, ptr) == DYN_NO_ERROR)

return 0;

return -1;

}

See Also

dyn_ValidateImage, dyn_GetNumSections, dyn_GetSections, dyn_Get-

StringTableSize, dyn_GetStringTable, dyn_GetExpSymTab,

dyn_LookupByName, dyn_Relocate, dyn_AllocSectionMem,

dyn_CopySectionContents

Returned Value Reason

DYN_NO_ERROR Success. The address has been recorded within the native

section table copy.

DYN_BAD_PTR The sections or image parameter is NULL, or there is no

section secnum. This value is also returned if the section

already has an address assigned, or it has already been relo-

cated.

Documented Library Functions

1-194 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

dyn_SetSectionMem

Specify the target address of a dynamically-loadable section

Synopsis

#include <libdyn.h>

DYN_RESULT dyn_SetSectionMem(dyn_mem_image *image,

dyn_section *sections,

size_t secnum,

uint32_t taddr,

dyn_section_mem **memptr);

Description

The dyn_SetSectionMem function creates internal house-keeping mem-

ory for a given section within a dynamically-loadable module (DLM), and

records the target address at which the section will reside. image is the

DLM, validated by dyn_ValidateImage. sections is a native copy of the

DLM’s section table, obtained by dyn_GetSections. secnum is the number

for the section for which to set the address. taddr is the target address.

In this context, the target address refers to the address at which the section

will begin, when relocated.

The function will create a dyn_section_mem structure, pointed to by

*memptr, which can be passed to dyn_SetSectionAddr.

CrossCore Embedded Studio 1.1 1-195

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

Error Conditions

The dyn_SetSectionMem function returns a status value indicating suc-

cess, or the reason for failure, as follows.

Example

#include <libdyn.h>

dyn_section_mem *set_addr(dyn_mem_image *image,

dyn_section *secs,

size_t num, uint32_t addr) {

dyn_section_mem *mem = 0;

if (dyn_SetSectionMem(image, secs, num, addr, &mem) ==

DYN_NO_ERROR)

return 0;

return mem;

}

See Also

dyn_ValidateImage, dyn_GetNumSections, dyn_GetSections, dyn_Get-

StringTableSize, dyn_GetStringTable, dyn_GetExpSymTab,

dyn_LookupByName, dyn_Relocate, dyn_AllocSectionMem,

dyn_CopySectionContents

Returned Value Reason

DYN_NO_ERROR Success. The address has been recorded within the native

section table copy.

DYN_BAD_PTR The image, sections or memptr parameter is NULL.

DYN_BAD_IMAGE There is no section secnum.

DYN_NO_MEM There is insufficient memory to allocate the internal

house-keeping structures.

Documented Library Functions

1-196 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

dyn_ValidateImage

Verify a memory buffer contains a valid dynamically-loadable module

Synopsis

#include <libdyn.h>

DYN_RESULT dyn_ValidateImage(void *ptr,

size_t len,

dyn_mem_image *image);

Description

The dyn_ValidateImage function accepts a pointer to a block of memory,

and performs various checks to determine whether the memory contains a

validate dynamically-loadable module (DLM), as produced by elf2dyn.

The memory buffer is pointed to by ptr, and must be at least len charac-

ters in size. If the buffer does contain a valid DLM, the function will

populate the structure pointed to by image; the resulting image pointer

will be suitable for passing to other DLM-handling functions.

Error Conditions

The dyn_ValidateImage function returns a status value indicating success,

or the reason for failure, as follows.

Returned Value Reason

DYN_NO_ERROR Success. The buffer contains a valid DLM.

DYN_BAD_PTR The ptr or image parameter is NULL.

DYN_TOO_SMALL The memory buffer as described by ptr/len is too small to

contain any DLM, or the DLM’s sections/relocations

exceed the buffer.

DYN_BAD_IMAGE The image does not have the right magic number, or offsets

within the image are nonsensical.

CrossCore Embedded Studio 1.1 1-197

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

Example

#include <stdio.h>

#include <libdyn.h>

static dyn_mem_image dlm_info;

int check_dlm(FILE *fp, char *buf, size_t maxlen) {

size_t len = fread(buf, 1, maxlen, fp);

if (dyn_ValidateImage(buf, len, &dlm_info) == DYN_NO_ERROR)

return 0;

return -1;

}

See Also

dyn_GetNumSections, dyn_GetSections, dyn_GetStringTableSize,

dyn_GetStringTable, dyn_GetExpSymTab, dyn_LookupByName,

dyn_Relocate, dyn_SetSectionAddr, dyn_AllocSectionMem,

dyn_CopySectionContents

DYN_BAD_VERSION The DLM’s version number is not a version supported by

this instance of libdyn.

DYN_BAD_FAMILY The DLM is for a processor family not recognized by this

instance of libdyn.

Returned Value Reason

Documented Library Functions

1-198 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

exit

Normal program termination

Synopsis

#include <stdlib.h>

void exit (int status);

Description

The exit function causes normal program termination. The functions reg-

istered by the atexit function are called in reverse order of their

registration and the processor is put into the IDLE state. The status argu-

ment is stored in register R0, and control is passed to the label

___lib_prog_term, which is defined in the run-time startup file.

Error Conditions

None.

Example

#include <stdlib.h>

exit (EXIT_SUCCESS);

See Also

abort, atexit

CrossCore Embedded Studio 1.1 1-199

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

exp

Exponential

Synopsis

#include <math.h>

float expf (float x);

double exp (double x);

long double expd (long double x);

Description

The exponential functions compute the exponential value e to the power

of their argument.

Error Conditions

The input argument x for expf must be in the domain [-87.33, 88.72] and

the input argument for expd must be in the domain [-708.2, 709.1]. The

functions return HUGE_VAL if x is greater than the domain and 0.0 if x is

less than the domain.

Example

#include <math.h>

double y;

float x;

y = exp (1.0); /* y = 2.71828 */

x = expf (1.0); /* x = 2.71828 */

See Also

log, pow

Documented Library Functions

1-200 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

fabs

Absolute value

Synopsis

#include <math.h>

float fabsf (float x);

double fabs (double x);

long double fabsd (long double x);

Description

The fabs functions return the absolute value of the argument x.

Error Conditions

None.

Example

#include <math.h>

double y;

float x;

y = fabs (-2.3); /* y = 2.3 */

y = fabs (2.3); /* y = 2.3 */

x = fabsf (-5.1); /* x = 5.1 */

See Also

abs, absfx, labs, llabs

CrossCore Embedded Studio 1.1 1-201

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

fclose

Close a stream

Synopsis

#include <stdio.h>

int fclose(FILE *stream);

Description

The fclose function flushes stream and closes the associated file. The flush

will result in any unwritten buffered data for the stream to be written to

the file, with any unread buffered data being discarded.

If the buffer associated with stream was allocated automatically it will be

deallocated.

The fclose function will return 0 on successful completion.

Error Conditions

If the fclose function is not successful it returns EOF.

Example

#include <stdio.h>

void example(char* fname)

{

FILE *fp;

fp = fopen(fname, "w+");

/* Do some operations on the file */

fclose(fp);

}

Documented Library Functions

1-202 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

See Also

fopen

CrossCore Embedded Studio 1.1 1-203

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

feof

Test for end of file

Synopsis

#include <stdio.h>

int feof(FILE *stream);

Description

The feof function tests whether or not the file identified by stream has

reached the end of the file. The routine returns 0 if the end of the file has

not been reached and a non-zero result of the end of file has been reached.

Error Conditions

None.

Example

#include <stdio.h>

void print_char_from_file(FILE *fp)

{

/* printf out each character from a file until EOF */

while (!feof(fp))

printf("%c", fgetc(fp));

printf("\n");

}

See Also

clearerr, ferror

Documented Library Functions

1-204 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

ferror

Test for read or write errors

Synopsis

#include <stdio.h>

int ferror(FILE *stream);

Description

The ferror function tests whether an uncleared error has occurred while

accessing stream. If there are no errors then the function will return zero,

otherwise it will return a non-zero value.

The ferror function does not examine whether the file identified by

stream has reached the end of the file.

Error Conditions

None.

Example

#include <stdio.h>

void test_for_error(FILE *fp)

{

if (ferror(fp))

printf("Error with read/write to stream\n");

else

printf("read/write to stream OKAY\n");

}

See Also

clearerr, feof

CrossCore Embedded Studio 1.1 1-205

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

fflush

Flush a stream

Synopsis

#include <stdio.h>

int fflush(FILE *stream);

Description

The fflush function causes any unwritten data for stream to be written to

the file. If stream is a NULL pointer, fflush performs this flushing action

on all streams.

Upon successful completion the fflush function returns zero.

Error Conditions

If fflush is unsuccessful, the EOF value is returned.

Example

#include <stdio.h>

void flush_all_streams(void)

{

fflush(NULL);

}

See Also

fclose

Documented Library Functions

1-206 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

fgetc

Get a character from a stream

Synopsis

#include <stdio.h>

int fgetc(FILE *stream);

Description

The fgetc function obtains the next character from the input stream

pointed to by stream, converts it from an unsigned char to an int and

advances the file position indicator for the stream.

If there are no errors, then fgetc will return the next character as the func-

tion result.

Error Conditions

If the fgetc function is unsuccessful, EOF is returned.

Example

#include <stdio.h>

char use_fgetc(FILE *fp)

{

char ch;

if ((ch = fgetc(fp)) == EOF) {

printf("Read End-of-file\n")

return 0;

} else {

return ch;

}

CrossCore Embedded Studio 1.1 1-207

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

See Also

getc

Documented Library Functions

1-208 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

fgetpos

Record the current position in a stream

Synopsis

#include <stdio.h>

int fgetpos(FILE *stream, fpos_t *pos);

Description

The fgetpos function stores the current value of the file position indicator

for the stream pointed to by stream in the file position type object pointed

to by pos. The information generated by fgetpos in pos can be used with

the fsetpos function to return the file to this position.

Upon successful completion the fgetpos function will return 0.

Error Conditions

If fgetpos is unsuccessful, the function will return a non-zero value.

Example

#include <stdio.h>

void aroutine(FILE *fp, char *buffer)

{

fpos_t pos;

/* get the current file position */

if (fgetpos(fp, &pos)!= 0) {

printf("fgetpos failed\n");

return;

}

/* write the buffer to the file */

(void) fprintf(fp, "%s\n", buffer);

/* reset the file position to the value before the write */

CrossCore Embedded Studio 1.1 1-209

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

if (fsetpos(fp, &pos) != 0) {

printf("fsetpos failed\n");

}

See Also

fsetpos, ftell, fseek, rewind

Documented Library Functions

1-210 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

fgets

Get a string from a stream

Synopsis

#include <stdio.h>

char *fgets(char *s, int n, FILE *stream);

Description

The fgets function reads characters from stream into the array pointed to

by s. The function will read a maximum of one less character than the

value specified by n, although the get will also end if either a NEWLINE char-

acter or the end-of-file marker are read. The array s will have a NUL

character written at the end of the string that has been read.

Upon successful completion the fgets function will return s.

Error Conditions

If fgets is unsuccessful, the function will return a NULL pointer.

Example

#include <stdio.h>

char buffer[20];

void read_into_buffer(FILE *fp)

{

char *str;

str = fgets(buffer, sizeof(buffer), fp);

if (str == NULL) {

CrossCore Embedded Studio 1.1 1-211

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

printf("Either read failed or EOF encountered\n");

} else {

printf("filled buffer with %s\n", str);

}

See Also

fgetc, getc, gets

Documented Library Functions

1-212 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

fileno

Get the file descriptor for a stream

Synopsis

#include <stdio.h>

int fileno(FILE *stream);

Description

The fileno function returns the file descriptor for a stream. The file

descriptor is an opaque value used by the extensible device driver interface

to represent the open file. The resulting value may only be used as a

parameter to other functions that accept file descriptors.

Error Conditions

The fileno function returns -1 if it detects that stream is not valid or is not

open. If successful, it returns a positive value.

Example

#include <stdio.h>

int apply_control_cmd(FILE *fp, int cmd, int val) {

int fildes = fileno(fp);

return ioctl(fildes, cmd, val);

}

See Also

fopen, ioctl

CrossCore Embedded Studio 1.1 1-213

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

floor

Floor

Synopsis

#include <math.h>

float floorf (float x);

double floor (double x);

long double floord (long double x);

Description

The floor functions return the largest integral value that is not greater

than their argument.

Error Conditions

None.

Example

#include <math.h>

double y;

float z;

y = floor (1.25); /* y = 1.0 */

y = floor (-1.25); /* y = -2.0 */

z = floorf (10.1); /* z = 10.0 */

See Also

ceil

Documented Library Functions

1-214 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

fmod

Floating-point modulus

Synopsis

#include <math.h>

float fmodf (float x, float y);

double fmod (double x, double y);

long double fmodd (long double x, long double y);

Description

The fmod functions compute the floating-point remainder that results

from dividing the first argument by the second argument.

The result is less than the second argument and has the same sign as the

first argument. If the second argument is equal to zero, the fmod func-

tions return zero.

Error Conditions

None.

Example

#include <math.h>

double y;

float x;

y = fmod (5.0, 2.0); /* y = 1.0 */

x = fmodf (4.0, 2.0); /* x = 0.0 */

See Also

div, ldiv, modf

CrossCore Embedded Studio 1.1 1-215

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

fopen

Open a file

Synopsis

#include <stdio.h>

FILE *fopen(const char *filename, const char *mode);

Description

The fopen function initializes the data structures that are required for

reading or writing to a file. The file’s name is identified by filename, with

the access type required specified by the string mode.

Valid selections for mode are specified below. If any other mode specifica-

tion is selected then the behavior is undefined.

mode Selection

rOpen text file for reading. This operation fails if the file has not previ-

ously been created.

wOpen text file for writing. If the filename already exists then it will be

truncated to zero length with the write starting at the beginning of the

file. If the file does not already exist then it is created.

aOpen a text file for appending data. All data will be written to the end of

the file specified.

r+ As r with the exception that the file can also be written to.

w+ As w with the exception that the file can also be read from.

a+ As a with the exception that the file can also be read from any position

within the file. Data is only written to the end of the file.

rb As r with the exception that the file is opened in binary mode.

wb As w with the exception that the file is opened in binary mode.

ab As a with the exception that the file is opened in binary mode.

r+b/rb+ Open file in binary mode for both reading and writing.

Documented Library Functions

1-216 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

If the call to the fopen function is successful a pointer to the object con-

trolling the stream is returned.

Error Conditions

If the fopen function is not successful a NULL pointer is returned.

Example

#include <stdio.h>

FILE *open_output_file(void)

{

/* Open file for writing as binary */

FILE *handle = fopen("output.dat", "wb");

return handle;

}

See Also

fclose, fflush, freopen

w+b/wb+ Create or truncate to zero length a file for both reading and writing.

a+b/ab+ As a+ with the exception that the file is opened in binary mode.

mode Selection

CrossCore Embedded Studio 1.1 1-217

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

fprintf

Print formatted output

Synopsis

#include <stdio.h>

int fprintf(FILE *stream, const char *format, /*args*/ ...);

Description

The fprintf function places output on the named output stream. The

string pointed to by format specifies how the arguments are converted for

output.

The format string can contain zero or more conversion specifications, each

beginning with the % character. The conversion specification itself follows

the % character and consists of one or more of the following sequence:

• Flag – optional characters that modifies the meaning of the

conversion.

• Width – optional numeric value (or *) that specifies the minimum

field width.

• Precision – optional numeric value that gives the minimum num-

ber of digits to appear.

• Length – optional modifier that specifies the size of the argument.

• Type – character that specifies the type of conversion to be applied.

Documented Library Functions

1-218 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

The flag characters can be in any order and are optional. The valid flags

are described in Table 1-35.

If a field width is specified, the converted value is padded with spaces to

the specified width if the converted value contains fewer characters than

the width. Normally spaces will be used to pad the field on the left, but

padding on the right will be used if the ‘-’ flag has been specified. The ‘0’

flag may be used as an alternative to space padding; see the description of

the flag field above. The width may also be specified as a ‘*’, which indi-

cates that the current argument in the call to fprintf is an int that defines

the value of the width. If the value is negative then it is interpreted as a ‘-’

flag and a positive field width.

Table 1-35. Valid Flags for fprintf Function

Flag Field

-Left justify the result within the field. The result is right-justified by

default.

+Always begin a signed conversion with a plus or minus sign. By default

only negative values will start with a sign.

space Prefix a space to the result if the first character is not a sign and the +

flag has not also been specified.

#The result is converted to an alternative form depending on the type of

conversion:

o : If the value is not zero it is preceded with 0.

x : If the value is not zero it is preceded with 0x.

X : If the value is not zero it is preceded with 0X.

a A e E f F: Always generate a decimal point.

g G : as E except trailing zeros are not removed.

0 (zero) Specifies an alternative to space padding. Leading zeroes will be used as

necessary to pad a field to the specified field width, the leading zeroes

will follow any sign or specification of a base. The flag will be ignored if

it appears with a ‘-’ flag or if it is used in a conversion specification that

uses a precision and one of the conversions a, A, d, i, o, u, x or X.

The 0 flag may be used with the a, A, d, i, o, u, x, X, e, E, f, g and G

conversions.

CrossCore Embedded Studio 1.1 1-219

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

The optional precision value always begins with a period (.) and is fol-

lowed either by an asterisk (*) or by a decimal integer. An asterisk (*)

indicates that the precision is specified by an integer argument preceding

the argument to be formatted. If only a period is specified, a precision of

zero will be assumed. The precision value has differing effects depending

on the conversion specifier being used:

•For A, a specifies the number of digits after the decimal point. If

the precision is zero and the # flag is not specified no decimal point

will be generated.

•For d,i,o,u,x,X specifies the minimum number of digits to

appear, defaulting to 1.

•For f,F,E,e,r,R specifies the number of digits after the decimal

point character, the default being 6. If the # specifier is present

with a zero precision then no decimal point will be generated.

•For g, G specifies the maximum number of significant digits.

•For s specifies the maximum number of characters to be written.

The length modifier (Table 1-36) can optionally be used to specify the

size of the argument. The length modifiers should only precede one of the

d, i, o, u, x, X, r, R or n conversion specifiers unless other conversion

specifiers are detailed.

Table 1-36. Length Modifiers for fprintf Function

Length Action

hThe argument should be interpreted as a short int. If preceding the r or

R conversion specifier, the argument is interpreted as short fract or

unsigned short fract.

lThe argument should be interpreted as a long int. If preceding the r or

R conversion specifier, the argument is interpreted as long fract or

unsigned long fract

Documented Library Functions

1-220 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

Table 1-37 contains definitions of the valid conversion specifiers that

define the type of conversion to be applied.

ll The argument should be interpreted as a long long int.

LThe argument should be interpreted as a long double argument. This

length modifier should precede one of the a, A, e, E, f, F, g, or G

conversion specifiers. Note that this length modifier is only valid if

-double-size-64 is selected. If -double-size-32 is selected no con-

version will occur, with the corresponding argument being consumed.

Table 1-37. Valid Conversion Specifier Definitions for fprintf Function

Specifier Conversion

a, A floating-point, hexadecimal notation

ccharacter

d, i signed decimal integer

e, E floating-point, scientific notation (mantissa/exponent)

f, F floating-point, decimal notation

g, G convert as e, E or f, F

npointer to signed integer to which the number of characters written so

far will be stored with no other output

ounsigned octal

ppointer to void

rsigned fract

Runsigned fract

sstring of characters

uunsigned integer

x, X unsigned hexadecimal notation

%print a % character with no argument conversion

Table 1-36. Length Modifiers for fprintf Function (Cont’d)

Length Action

CrossCore Embedded Studio 1.1 1-221

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

The a|A conversion specifier converts to a floating-point number with the

notational style [-]0xh.hhhh±d where there is one hexadecimal digit

before the period. The a|A conversion specifiers always contain a mini-

mum of one digit for the exponent.

The e|E conversion specifier converts to a floating-point number nota-

tional style [-]d.ddde±dd. The exponent always contains at least two

digits. The case of the e preceding the exponent will match that of the

conversion specifier.

The f|F conversion specifies to convert to decimal notation [-]d.ddd±ddd.

The g|G conversion specifier converts as e|E or f|F specifiers depending on

the value being converted. If the value being converted is less than -4 or

greater than or equal to the precision then e|E conversions will be used,

otherwise f|F conversions will be used.

For all of the a, A, e, E, f, F, g and G specifiers an argument that represents

infinity is displayed as Inf. For all of the a, A, e, E, f, F, g and G specifiers

an argument that represents a NaN result is displayed as NaN.

The r|R conversion specifiers convert a fixed-point value to decimal nota-

tion [-]d.ddd if you are linking with the fixed-point I/O library using the

-flags-link -MD__LIBIO_FX switch. Otherwise they will convert a

fixed-point value to hexadecimal.

The fprintf function returns the number of characters printed.

Error Conditions

If the fprintf function is unsuccessful, a negative value is returned.

Documented Library Functions

1-222 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

Example

#include <stdio.h>

void fprintf_example(void)

{

char *str = "hello world";

/* Output to stdout is " +1 +1." */

fprintf(stdout, "%+5.0f%+#5.0f\n", 1.234, 1.234);

/* Output to stdout is "1.234 1.234000 1.23400000" */

fprintf(stdout, "%.3f %f %.8f\n", 1.234, 1.234, 1.234);

/* Output to stdout is "justified:

left:5 right: 5" */

fprintf(stdout, "justified:\nleft:%-5dright:%5i\n", 5, 5);

/* Output to stdout is

"90% of test programs print hello world" */

fprintf(stdout, "90%% of test programs print %s\n", str);

/* Output to stdout is "0.0001 1e-05 100000 1E+06" */

fprintf(stdout, "%g %g %G %G\n", 0.0001, 0.00001, 1e5, 1e6);

}

See Also

printf, snprintf, vfprintf, vprintf, vsnprintf, vsprintf

CrossCore Embedded Studio 1.1 1-223

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

fputc

Put a character on a stream

Synopsis

#include <stdio.h>

int fputc(int ch, FILE *stream);

Description

The fputc function writes the argument ch to the output stream pointed

to by stream and advances the file position indicator. The argument ch is

converted to an unsigned char before it is written.

If the fputc function is successful then it will return the value that was

written to the stream.

Error Conditions

If the fputc function is not successful EOF is returned.

Example

#include <stdio.h>

void fputc_example(FILE* fp)

{

/* put the character 'i' to the stream pointed to by fp */

int res = fputc('i', fp);

if (res != 'i')

printf("fputc failed\n");

}

See Also

putc

Documented Library Functions

1-224 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

fputs

Put a string on a stream

Synopsis

#include <stdio.h>

int fputs(const char *string, FILE *stream);

Description

The fputs function writes the string pointed to by string to the output

stream pointed to by stream. The NULL terminating character of the string

will not be written to stream.

If the call to fputs is successful, the function returns a non-negative value.

Error Conditions

The fputs function will return EOF if a write error occurred.

Example

#include <stdio.h>

void fputs_example(FILE* fp)

{

/* put the string "example" to the stream pointed to by fp */

char *example = "example";

int res = fputs(example, fp);

if (res == EOF)

printf("fputs failed\n");

}

See Also

puts

CrossCore Embedded Studio 1.1 1-225

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

fread

Buffered input

Synopsis

#include <stdio.h>

size_t fread(void *ptr, size_t size, size_t n, FILE *stream);

Description

The fread function reads into an array pointed to by ptr up to a maximum

of n items of data from stream, where each item of data is of length size.

It stops reading data if an EOF or error condition is encountered while

reading from stream, or if n items have been read. It advances the data

pointer in stream by the number of characters read. It does not change the

contents of stream.

The fread function returns the number of items read, this may be less than

n if there is insufficient data on the external device to satisfy the read

request. If size or n is zero, then fread will return zero and does not affect

the state of stream.

When the stream has been opened as a binary stream, the Analog Devices

I/O library may choose to bypass the I/O buffer and transmit data from an

external device directly into the program, particularly when the buffer size

(as defined by the macro BUFSIZ in the stdio.h header file, or controlled

by the function setvbuf) is smaller than the number of characters to be

transferred.

Normally, binary streams are a bit-exact mirror image of the processor’s

memory such that data that is written out to a binary stream can be later

read back unmodified. The size of a binary file on SHARC architecture is

therefore normally a multiple of 32-bit words. When the size of a file is

not a multiple of four, fread will behave as if the file was padded out by a

sufficient number of trailing null characters to bring the size of the file up

to the next multiple of 32-bit words.

Documented Library Functions

1-226 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

Error Conditions

If an error occurs, fread returns zero and sets the error indicator for

stream.

Example

#include <stdio.h>

int buffer[100];

int fill_buffer(FILE *fp)

{

int read_items;

/* Read from file pointer fp into array buffer */

read_items = fread(&buffer, sizeof(int), 100, fp);

if (read_items < 100) {

if (ferror(fp))

printf("fill_buffer failed with an I/O error\n");

else if (feof(fp))

printf("fill_buffer failed with EOF\n");

else

printf("fill_buffer only read %d items\n",read_items);

}

return read_items;

}

See Also

ferror, fgetc, fgets, fscanf

CrossCore Embedded Studio 1.1 1-227

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

free

Deallocate memory

Synopsis

#include <stdlib.h>

void free (void *ptr);

Description

The free function deallocates a pointer previously allocated to a range of

memory to the free memory heap. If the pointer was not previously allo-

cated by calloc, malloc, realloc, heap_calloc, heap_malloc, or

heap_realloc, the behavior is undefined.

The free function returns the allocated memory to the heap from which it

was allocated.

Error Conditions

None.

Example

#include <stdlib.h>

char *ptr;

ptr = malloc (10); /* Allocate 10 words from heap */

free (ptr); /* Return space to free heap */

See Also

calloc, heap_calloc, heap_free, heap_lookup, heap_malloc, heap_realloc,

malloc, realloc, heap_space_unused

Documented Library Functions

1-228 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

freopen

Open a file using an existing file descriptor

Synopsis

#include <stdio.h>

FILE *freopen(const char *fname, const char *mode, FILE *stream);

Description

The freopen function opens the file specified by fname and associates it

with the stream pointed to by stream. The mode argument has the same

effect as described in fopen. (See fopen for more information on the mode

argument.)

Before opening the new file the freopen function will first attempt to flush

the stream and close any file descriptor associated with stream. Failure to

flush or close the file successfully is ignored. Both the error and EOF indi-

cators for stream are cleared.

The original stream will always be closed regardless of whether the open-

ing of the new file is successful or not.

Upon successful completion the freopen function returns the value of

stream.

Error Conditions

If freopen is unsuccessful, a NULL pointer is returned.

CrossCore Embedded Studio 1.1 1-229

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

Example

#include <stdio.h>

void freopen_example(FILE* fp)

{

FILE *result;

char *newname = "newname";

/* reopen existing file pointer for reading file "newname" */

result = freopen(newname, "r", fp);

if (result == fp)

printf("%s reopened for reading\n", newname);

else

printf("freopen not successful\n");

}

See Also

fclose, fopen

Documented Library Functions

1-230 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

frexp

Separate fraction and exponent

Synopsis

#include <math.h>

float frexpf (float x, int *expptr);

double frexp (double x, int *expptr);

long double frexpd (long double x, int *expptr);

Description

The frexp functions separate a floating-point input into a normalized frac-

tion and a (base 2) exponent. The functions return a fraction in the

interval [½, 1), and store a power of 2 in the integer pointed to by the sec-

ond argument. If the input is zero, then both the fraction and the

exponent is set to zero.

Error Conditions

None.

Example

#include <math.h>

double y;

float x;

int exponent;

y = frexp (2.0, &exponent); /* y = 0.5, exponent = 2 */

x = frexpf (4.0, &exponent); /* x = 0.5, exponent = 3 */

CrossCore Embedded Studio 1.1 1-231

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

See Also

modf

Documented Library Functions

1-232 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

fscanf

Read formatted input

Synopsis

#include <stdio.h>

int fscanf(FILE *stream, const char *format, /* args */...);

Description

The fscanf function reads from the input file stream, interprets the inputs

according to format and stores the results of the conversions (if any) in its

arguments. The format is a string containing the control format for the

input with the following arguments as pointers to the locations where the

converted results are written.

The string pointed to by format specifies how the input is to be parsed

and, possibly, converted. It may consist of whitespace characters, ordinary

characters (apart from the % character), and conversion specifications. A

sequence of whitespace characters causes fscanf to continue to parse the

input until either there is no more input or until it find a non-whitespace

character. If the format specification contains a sequence of ordinary char-

acters then fscanf will continue to read the next characters in the input

stream until the input data does not match the sequence of characters in

the format. At this point fscanf will fail, and the differing and subsequent

characters in the input stream will not be read.

The % character in the format string introduces a conversion specification.

A conversion specification has the following form:

% [*] [width] [length] type

A conversion specification always starts with the % character. It may

optionally be followed by an asterisk (*) character, which indicates that

the result of the conversion is not to be saved. In this context the asterisk

character is known as the assignment-suppressing character. The optional

CrossCore Embedded Studio 1.1 1-233

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

token width represents a non-zero decimal number and specifies the maxi-

mum field width. fscanf will not read any more than width characters

while performing the conversion specified by type. The length token can

be used to define a length modifier.

The length modifier (Table 1-38) can be used to specify the size of the

argument. The length modifiers should only precede one of the d, i, o, u,

x, X, r, R or n conversion specifiers unless other conversion specifiers are

detailed.

The hh, j, t, and z size specifiers are defined in the C99 (ISO/IEC

9899:1999) standard.

Table 1-38. Length Modifiers for fscanf Function

Length Action

hThe argument should be interpreted as a short int. If preceding the r or

R conversion specifier, the argument is interpreted as short fract or

unsigned short fract.

hh The argument should be interpreted as a char.

jThe argument should be interpreted as intmax_t or uintmax_t.

lThe argument should be interpreted as a long int. If preceding the r or

R conversion specifier, the argument is interpreted as long fract or

unsigned long fract.

ll The argument should be interpreted as a long long int.

LThe argument should be interpreted as a long double argument. This

length modifier should precede one of the a, A, e, E, f, F, g, or G

conversion specifiers.

tThe argument should be interpreted as ptrdiff_t.

zThe argument should be interpreted as size_t.

Documented Library Functions

1-234 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

A definition of the valid conversion specifier characters that specify the

type of conversion to be applied can be found in Table 1-39.

The [ conversion specifier should be followed by a sequence of characters,

referred to as the scanset, with a terminating ] character and so will take

the form [scanset]. The conversion specifier copies into an array which is

the corresponding argument until a character that does not match any of

the scanset is read. If the scanset begins with a ^ character then the scan-

ning will match against characters not defined in the scanset. If the scanset

is to include the ] character then this character must immediately follow

the [ character or the ^ character if specified.

Table 1-39. Valid Conversion Specifier Definitions for fscanf Function

Specifier Conversion

a, A, e, E, f, F,

g, G

floating point, optionally preceded by a sign and optionally followed by

an e or E character

csingle character, including whitespace

dsigned decimal integer with optional sign

isigned integer with optional sign

nno input is consumed. The number of characters read so far will be writ-

ten to the corresponding argument. This specifier does not affect the

function result returned by fscanf

ounsigned octal

ppointer to void

rsigned fract with optional sign

Runsigned fract

sstring of characters up to a whitespace character

uunsigned decimal integer

x, X hexadecimal integer with optional sign

[a non-empty sequence of characters referred to as the scanset

%a single % character with no conversion or assignment

CrossCore Embedded Studio 1.1 1-235

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

Each input item is converted to a type appropriate to the conversion char-

acter, as specified in the table above. The result of the conversion is placed

into the object pointed to by the next argument that has not already been

the recipient of a conversion. If the suppression character has been speci-

fied then no data shall be placed into the object with the next conversion

using the object to store its result.

Note that the r and R format specifiers are only supported when linking

with the fixed-point I/O library using -flags-link -MD__LIBIO_FX.

The fscanf function returns the number of items successfully read.

Error Conditions

If the fscanf function is not successful before any conversion then EOF is

returned.

Example

#include <stdio.h>

void fscanf_example(FILE *fp)

{

short int day, month, year;

float f1, f2, f3;

char string[20];

/* Scan a date with any separator, eg, 1-1-2006 or 1/1/2006 */

fscanf (fp, "%hd%*c%hd%*c%hd", &day, &month, &year);

/* Scan float values separated by "abc", for example

1.234e+6abc1.234abc234.56abc */

fscanf (fp, "%fabc%gabc%eabc", &f1, &f2, &f3);

Documented Library Functions

1-236 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

/* For input "alphabet", string will contain "a" */

writ(fp, "%[aeiou]", string);

/* For input "drying”, string will contain "dry" */

fscanf (fp, "%[^aeiou]", string);

}

See Also

scanf, sscanf

CrossCore Embedded Studio 1.1 1-237

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

fseek

Reposition a file position indicator in a stream

Synopsis

#include <stdio.h>

int fseek(FILE *stream, long offset, int whence);

Description

The fseek function sets the file position indicator for the stream pointed to

by stream. The position within the file is calculated by adding the offset

to a position dependent on the value of whence. The valid values and

effects for whence are as follows.

Using fseek to position a text stream is only valid if either offset is zero,

or if whence is SEEK_SET and offset is a value that was previously returned

by ftell. For binary streams the offset is measured in addressable units of

memory, which on SHARC is 32-bit words.

Positioning within a file that has been opened as a text stream is

only supported by the libraries that Analog Devices supply if the

lines within the file are terminated by the character sequence \r\n.

A successful call to fseek will clear the EOF indicator for stream and

undoes any effects of ungetc on stream. If the stream has been opened as a

update stream, then the next I/O operation may be either a read request or

a write request.

whence Effect

SEEK_SET Set the position indicator to be equal to offset characters from the

beginning of stream.

SEEK_CUR Set the new position indicator to current position indicator for stream

plus offset.

SEEK_END Set the position indicator to EOF plus offset.

Documented Library Functions

1-238 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

Error Conditions

If the fseek function is unsuccessful, a non-zero value is returned.

Example

#include <stdio.h>

long fseek_and_ftell(FILE *fp)

{

long offset;

/* seek to 20 characters offset from given file pointer */

if (fseek(fp, 20, SEEK_SET) != 0) {

printf("fseek failed\n");

return -1;

}

/* Now use ftell to get the offset value back */

offset = ftell(fp);

if (offset == -1)

printf("ftell failed\n");

if (offset == 20)

printf("ftell and fseek work\n");

return offset;

}

See Also

fflush, ftell, ungetc

CrossCore Embedded Studio 1.1 1-239

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

fsetpos

Reposition a file pointer in a stream

Synopsis

#include <stdio.h>

int fsetpos(FILE *stream, const fpos_t *pos);

Description

The fsetpos function sets the file position indicator for stream, using the

value of the object pointed to by pos. The value pointed to by pos must be

a value obtained from an earlier call to fgetpos on the same stream.

Positioning within a file that has been opened as a text stream is

only supported by the libraries that Analog Devices supply if the

lines within the file are terminated by the character sequence \r\n.

A successful call to fsetpos function clears the EOF indicator for stream and

undoes any effects of ungetc on the same stream.

The fsetpos function returns zero if it is successful.

Error Conditions

If the fsetpos function is unsuccessful, the function returns a non-zero

value.

Example

See fgetpos for an example.

See Also

fgetpos, ftell, rewind, ungetc

Documented Library Functions

1-240 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

ftell

Obtain current file position

Synopsis

#include <stdio.h>

long int ftell(FILE *stream);

Description

The ftell function obtains the current position for a file identified by

stream.

If stream is a text stream, then the information in the position indicator is

unspecified information, usable by fseek for determining the file position

indicator at the time of the ftell call.

If stream is a binary stream, then ftell returns the current position as an

offset from the start of the file. As binary streams are normally bit-exact

images of the processor’s memory, the offset returned is in addressable

units of memory that, on a SHARC processor, is 32-bit words.

Positioning within a file that has been opened as a text stream is

only supported by the libraries that Analog Devices supply if the

lines within the file are terminated by the character sequence \r\n.

If successful, the ftell function returns the current value of the file position

indicator on the stream.

Error Conditions

If the ftell function is unsuccessful, a value of -1 is returned.

Example

See fseek for an example.

CrossCore Embedded Studio 1.1 1-241

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

See Also

fseek

Documented Library Functions

1-242 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

fwrite

Buffered output

Synopsis

#include <stdio.h>

size_t fwrite(const void *ptr, size_t size, size_t n,

FILE *stream);

Description

The fwrite function writes to the output stream up to n items of data from

the array pointed by ptr. An item of data is defined as a sequence of char-

acters of size size. The write will complete once n items of data have been

written to the stream. The file position indicator for stream is advanced

by the number of characters successfully written.

When the stream has been opened as a binary stream, the Analog Devices

I/O library may choose to bypass the I/O buffer and transmit data from

the program directly to the external device, particularly when the buffer

size (as defined by the macro BUFSIZ in the stdio.h header file, or con-

trolled by the function setvbuf) is smaller than the number of characters

to be transferred.

If successful then the fwrite function will return the number of items

written.

Error Conditions

If the fwrite function is unsuccessful, it will return the number of elements

successfully written which will be less than n.

CrossCore Embedded Studio 1.1 1-243

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

Example

#include <stdio.h>

char* message="some text";

void write_text_to_file(void)

{

/* Open "file.txt" for writing */

FILE* fp = fopen("file.txt", "w");

int res, message_len = strlen(message);

if (!fp) {

printf("fopen was not successful\n");

return;

}

res = fwrite(message, sizeof(char), message_len, fp);

if (res != message_len)

printf("fwrite was not successful\n");

}

See Also

fread

Documented Library Functions

1-244 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

fxbits

Bitwise integer to fixed-point to conversion

Synopsis

#include <stdfix.h>

short fract hrbits(int_hr_t b);

fract rbits(int_r_t b);

long fract lrbits(int_lr_t b);

unsigned short fract uhrbits(uint_uhr_t b);

unsigned fract urbits(uint_ur_t b);

unsigned long fract ulrbits(uint_ulr_t b);

Description

Given an integer operand, the fxbits family of functions return the integer

value divided by 2F, where F is the number of fractional bits in the result

fixed-point type. This is equivalent to the bit-pattern of the integer value

held in a fixed-point type.

Error Conditions

None. If the input integer value does not fit in the number of bits of the

fixed-point result type, the result is saturated to the largest or smallest

fixed-point value.

Example

#include <stdfix.h>

unsigned long fract ulr;

ulr = ulrbits(0x20000000); /* ulr == 0.125ulr */

See Also

bitsfx

CrossCore Embedded Studio 1.1 1-245

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

fxdivi

Division of integer by integer to give fixed-point result

Synopsis

#include <stdfix.h>

fract rdivi(int numer, int denom);

long fract lrdivi(long int numer, long int denom);

unsigned fract urdivi(unsigned int numer, unsigned int denom);

unsigned long fract ulrdivi(unsigned long int numer,

unsigned long int denom);

Description

Given an integer numerator and denominator, the fxdivi family of

functions computes the quotient and returns the closest fixed-point value

to the result.

Error Conditions

The fxdivi function has undefined behavior if the denominator is zero.

Example

#include <stdfix.h>

unsigned long fract ulquo;

ulquo = ulrdivi(1, 8); /* ulquo == 0.125ulr */

See Also

div, divifx, idivfx, ldiv, lldiv

Documented Library Functions

1-246 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

getc

Get a character from a stream

Synopsis

#include <stdio.h>

int getc(FILE *stream);

Description

The getc function is equivalent to fgetc. The getc function obtains the

next character from the input stream pointed to by stream, converts it

from an unsigned char to an int and advances the file position indicator

for the stream.

Upon successful completion the getc function will return the next charac-

ter from the input stream pointed to by stream.

Error Conditions

If the getc function is unsuccessful, EOF is returned.

Example

#include <stdio.h>

char use_getc(FILE *fp)

{

char ch;

if ((ch = getc(fp)) == EOF) {

printf("Read End-of-file\n");

return (char)-1;

} else {

return ch;

}

CrossCore Embedded Studio 1.1 1-247

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

See Also

fgetc

Documented Library Functions

1-248 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

getchar

Get a character from stdin

Synopsis

#include <stdio.h>

int getchar(void);

Description

The getchar function is functionally the same as calling the getc function

with stdin as its argument. A call to getchar will return the next single

character from the standard input stream. The getchar function also

advances the standard input’s current position indicator.

Error Conditions

If the getchar function is unsuccessful, EOF is returned.

Example

#include <stdio.h>

char use_getchar(void)

{

char ch;

if ((ch = getchar()) == EOF) {

printf("getchar() failed\n");

return (char)-1;

} else {

return ch;

}

CrossCore Embedded Studio 1.1 1-249

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

See Also

getc

Documented Library Functions

1-250 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

getenv

Get string definition from operating system

Synopsis

#include <stdlib.h>

char *getenv (const char *name);

Description

The getenv function polls the operating system to see if a string is defined.

There is no default operating system for the SHARC processors, so getenv

always returns NULL.

Error Conditions

None.

Example

#include <stdlib.h>

char *ptr;

ptr = getenv ("ADI_DSP"); /* ptr = NULL */

See Also

system

CrossCore Embedded Studio 1.1 1-251

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

gets

Get a string from a stream

Synopsis

#include <stdio.h>

char *gets(char *s);

Description

The gets function reads characters from the standard input stream into the

array pointed to by s. The read terminates when a NEWLINE character is

read, with the NEWLINE character being replaced by a null character in the

array pointed to by s. The read will also halt if EOF is encountered.

The array pointed to by s must be of equal or greater length of the input

line being read. If this is not the case, the behavior is undefined. If EOF is

encountered without any characters being read, then a NULL pointer is

returned.

Error Conditions

If the gets function is not successful and a read error occurs, then a NULL

pointer is returned.

Example

#include <stdio.h>

void fill_buffer(char *buffer)

{

if (gets(buffer) == NULL)

printf("gets failed\n");

else

printf("gets read %s\n", buffer);

}

Documented Library Functions

1-252 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

See Also

fgetc, fgets, fread, fscanf

CrossCore Embedded Studio 1.1 1-253

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

gmtime

Convert calendar time into broken-down time as UTC

Synopsis

#include <time.h>

struct tm *gmtime(const time_t *t);

Description

The gmtime function converts a pointer to a calendar time into a bro-

ken-down time in terms of Coordinated Universal Time (UTC). A

broken-down time is a structured variable, which is described in time.h.

The broken-down time is returned by gmtime as a pointer to static mem-

ory, which may be overwritten by a subsequent call to either gmtime, or to

localtime.

Error Conditions

None.

Example

#include <time.h>

#include <stdio.h>

time_t cal_time;

struct tm *tm_ptr;

cal_time = time(NULL);

if (cal_time != (time_t) -1) {

tm_ptr = gmtime(&cal_time);

printf("The year is %4d\n",1900 + (tm_ptr->tm_year));

}

Documented Library Functions

1-254 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

See Also

localtime, mktime, time

CrossCore Embedded Studio 1.1 1-255

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

heap_calloc

Allocate and initialize memory in a heap

Synopsis

#include <stdlib.h>

void *heap_calloc(int heap_index, size_t nelem, size_t size);

Description

The heap_calloc function is an Analog Devices extension to the ANSI

standard.

The heap_calloc function allocates from the heap identified by heap_in-

dex, an array containing nelem elements of size, and stores zeros in all the

elements of the array. If successful, it returns a pointer to this array; other-

wise, it returns a null pointer. You can safely convert the return value to

an object pointer of any type whose size is not greater than size. The

memory may be deallocated with the free or heap_free function.

For more information on creating multiple run-time heaps, see the section

“Using Multiple Heaps” in Chapter 1 of the C/C++ Compiler Manual for

SHARC Processors.

Error Conditions

The heap_calloc function returns the null pointer if unable to allocate the

requested memory.

Documented Library Functions

1-256 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

Example

#include <stdlib.h>

#include <stdio.h>

#pragma section(“seg_hp2”)

static char extra_heap[256];

int main()

{

char *buf;

int index, uid = 999; /* arbitrary userid for heap */

/* Install extra_heap[] as a heap */

index = heap_install(extra_heap, sizeof(extra_heap), uid);

if (index < 0) {

printf("installation failed\n");

return 1;

}

/* Allocate memory for 128 characters from extra_heap[] */

buf = (char *)heap_calloc(index,128,sizeof(char));

if (buf != 0) {

printf("Allocated space starting at %p\n", buf);

free(buf); /* free can be used to release the memory */

} else {

printf("Unable to allocate from extra_heap[]\n");

}

return 0;

}

See Also

calloc, free, heap_free, heap_malloc, heap_realloc, malloc, realloc,

heap_space_unused

CrossCore Embedded Studio 1.1 1-257

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

heap_free

Return memory to a heap

Synopsis

#include <stdlib.h>

void heap_free(int heap_index, void *ptr);

Description

The heap_free function is an Analog Devices extension to the ANSI

standard.

The heap_free function deallocates the object whose address is ptr, pro-

vided that ptr is not a null pointer. If the object was not allocated by one

of the heap allocation routines, or if the object has been previously freed,

then the behavior of the function is undefined. If ptr is a null pointer,

then the heap_free function will just return.

The function does not use the heap_index argument; instead it identifies

the heap from which the object was allocated and returns the memory to

this heap. For more information on creating multiple run-time heaps, see

the section “Using Multiple Heaps” in Chapter 1 of the C/C++ Compiler

Manual for SHARC Processors.

Error Conditions

None.

Example

#include <stdlib.h>

#include <stdio.h>

#pragma section(“seg_hp2”)

static char extra_heap[256];

Documented Library Functions

1-258 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

int main()

{

char *buf;

int index, uid = 999; /* arbitrary userid for heap */

/* Install extra_heap[] as a heap */

index = heap_install(extra_heap, sizeof(extra_heap), uid);

if (index < 0) {

printf("installation failed\n");

return 1;

}

/* Allocate memory for 128 characters from extra_heap[] */

buf = (char *)heap_calloc(index,128,sizeof(char));

if (buf != 0) {

printf("Allocated space starting at %p\n", buf);

heap_free(index, buf);

} else {

printf("Unable to allocate from extra_heap[]\n");

}

return 0;

}

See Also

calloc, free, heap_calloc, heap_malloc, heap_realloc, malloc, realloc,

heap_space_unused

CrossCore Embedded Studio 1.1 1-259

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

heap_init

Re-initialize a heap

Synopsis

#include <stdlib.h>

int heap_init(int heap_index);

Description

The heap_init function is an Analog Devices extension to the ANSI

standard.

The heap_init function re-initializes a heap, discarding all allocations

within the heap. Because the function discards any allocations within the

heap, it must not be used if there are any allocations on the heap that are

still active and may be used in the future.

The function returns a zero if it succeeds in re-initializing the heap

specified.

The run-time libraries use the default heap for data storage,

potentially before the application has reached main. Therefore,

re-initializing the default heap may result in erroneous or

unexpected behavior.

Error Conditions

The heap_init function returns a non-zero result if it failed to re-initialize

the heap.

Documented Library Functions

1-260 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

Example

#include <stdlib.h>

#include <stdio.h>

int heap_index = heap_lookup(USERID_HEAP);

if (heap_init(heap_index)!=0) {

printf("Heap re-initialization failed\n");

}

See Also

calloc, free,heap_calloc, heap_free, heap_space_unused, heap_install,

heap_lookup, heap_malloc, heap_realloc, malloc, realloc, space_unused

CrossCore Embedded Studio 1.1 1-261

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

heap_install

Sets up a heap at runtime

Synopsis

#include <stdlib.h>

int heap_install(void *base, size_t length, int userid);

Description

The heap_install function is an Analog Devices extension to the ANSI

standard.

The heap_install function sets up a memory heap (base) with a size speci-

fied by length at runtime. The dynamic heap is identified by the

userid.

Not all length words are available for user allocations. Some space is

reserved for administration.

On successful initialization, heap_install() returns the heap index allo-

cated for the newly installed heap. If the operation is unsuccessful, then

heap_install() returns -1.

Once the dynamic heap is initialized, heap space can be claimed using the

heap_malloc routine and associated heap management routines.

Error Conditions

The heap_install function returns -1 if initialization was unsuccessful.

Potential reasons include: there is not enough space available in the

__heaps table; a heap with the specified userid already exists; the space is

not large enough for the internal heap structures.

Documented Library Functions

1-262 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

Example

#include <stdlib.h>

#define EXTRAID 666

#define EXTRASZ 256

/* LDF must map this section to appropriate memory */

#pragma section(“runtime_heap”)

static char extra_heap[EXTRASZ];

int main()

{

int i;

int index;

int *x = NULL;

index = heap_install(extra_heap, EXTRASZ, EXTRAID);

if (index != -1)

x = heap_malloc(index, 90*sizeof(int));

if (x) {

for (i = 0; i < 90; i++)

x[i] = i;

}

return 0;

}

See Also

heap_malloc

CrossCore Embedded Studio 1.1 1-263

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

heap_lookup

Convert a userid to a heap index

Synopsis

#include <stdlib.h>

int heap_lookup(int userid);

Description

The heap_lookup function is an Analog Devices extension to the ANSI

standard.

The heap_lookup function converts a userid to a heap index. All heaps

have a userid and a heap index associated with them. Both the userid and

the heap index are set on heap creation. The default heap has userid 0

and heap index 0.

The heap index is required for the functions heap_calloc, heap_malloc,

heap_realloc, heap_init, and heap_space_unused. For more information

on creating multiple run-time heaps, see the section “Using Multiple

Heaps” in Chapter 1 of the C/C++ Compiler Manual for SHARC

Processors.

Error Conditions

The heap_lookup function returns -1 if there is no heap with the specified

userid.

Example

#include <stdlib.h>

#include <stdio.h>

int heap_userid = 1;

int heap_id;

Documented Library Functions

1-264 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

if ( (heap_id = heap_lookup(heap_userid)) == -1) {

printf("Lookup failed; will use the default heap\n");

heap_id = 0;

}

char *ptr = heap_malloc(heap_id, 1024);

if (ptr == NULL) {

printf("heap_malloc failed to allocate memory\n");

}

See Also

calloc, free,heap_calloc, heap_free, heap_init, heap_install,

heap_space_unused, heap_malloc, heap_realloc, malloc, realloc,

space_unused

CrossCore Embedded Studio 1.1 1-265

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

heap_malloc

Allocate memory from a heap

Synopsis

#include <stdlib.h>

void *heap_malloc(int heap_index, size_t size);

Description

The heap_malloc function is an Analog Devices extension to the ANSI

standard.

The heap_malloc function allocates an object of size from the heap iden-

tified by heap_index. It returns the address of the object if successful;

otherwise, it returns a null pointer. You can safely convert the return value

to an object pointer of any type whose size is not greater than size.

The block of memory is uninitialized. The memory may be deallocated

with the free or heap_free function.

For more information on multiple run-time heaps, see the section “Using

Multiple Heaps” in Chapter 1 of the C/C++ Compiler Manual for SHARC

Processors.

Error Conditions

The heap_malloc function returns the null pointer if unable to allocate

the requested memory.

Example

#include <stdlib.h>

#include <stdio.h>

#pragma section(“seg_hp2”)

Documented Library Functions

1-266 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

static char extra_heap[256];

int main()

{

char *buf;

int index, uid = 999; /* arbitrary userid for heap */

/* Install extra_heap[] as a heap */

index = heap_install(extra_heap, sizeof(extra_heap), uid);

if (index < 0) {

printf("installation failed\n");

return 1;

}

/* Allocate memory for 128 characters from extra_heap[] */

buf = (char *)heap_malloc(index,128);

if (buf != 0) {

printf("Allocated space starting at %p\n", buf);

heap_free(index, buf);

} else {

printf("Unable to allocate from extra_heap[]\n");

}

return 0;

}

See Also

calloc, free, heap_calloc, heap_free, heap_realloc, malloc, realloc,

heap_space_unused

CrossCore Embedded Studio 1.1 1-267

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

heap_realloc

Change memory allocation from a heap

Synopsis

#include <stdlib.h>

void *heap_realloc(int heap_index, void *ptr, size_t size);

Description

The heap_realloc function is an Analog Devices extension to the ANSI

standard.

The heap_realloc function changes the size of a previously allocated block

of memory. The new size of the object is specified by the argument size.

The modified object will contain the values of the old object up to mini-

mum(original size, new size), while for (new size > old size) any

data beyond the original size will be indeterminate.

If the function successfully re-allocated the object, then it will return a

pointer to the updated object. You can safely convert the return value to

an object pointer of any type whose size is not greater than size in length.

The behavior of the function is undefined if the object has already been

freed.

If ptr is a null pointer, then heap_realloc behaves the same as heap_mal-

loc and the block of memory returned will be uninitialized.

If ptr is not a null pointer, and if size is zero, then heap_realloc behaves

the same as heap_free.

The argument heap_index is only used if ptr is a null pointer.

The memory reallocated may be deallocated with the free or heap_free

function.

Documented Library Functions

1-268 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

For more information on multiple run-time heaps, see the section “Using

Multiple Heaps” in Chapter 1 of the C/C++ Compiler Manual for SHARC

Processors.

Error Conditions

The heap_realloc function returns the null pointer if unable to allocate the

requested memory; the original memory associated with ptr will be

unchanged and will still be available.

Example

#include <stdlib.h>

#include <stdio.h>

#pragma section(“seg_hp2”)

static char extra_heap[256];

int main()

{

char *buf, *upd;

int index, uid = 999; /* arbitrary userid for heap */

/* Install extra_heap[] as a heap */

index = heap_install(extra_heap, sizeof(extra_heap), uid);

if (index < 0) {

printf("installation failed\n");

return 1;

}

/* Allocate memory for 128 characters from extra_heap[] */

buf = (char *)heap_malloc(index, 128);

if (buf != 0) {

strcpy(buf,"hello");

/* Change allocated size to 200 */

upd = (char *)heap_realloc(index, buf, 200);

CrossCore Embedded Studio 1.1 1-269

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

if (upd != 0) {

printf("reallocated string for %s\n", upd);

heap_free(index, upd); /* Return to extra_heap[] */

} else {

free(buf); /* free can be used to release buf */

}

} else {

printf("Unable to allocate from extra_heap[]\n");

}

return 0;

}

See Also

calloc, free, heap_calloc, heap_free, heap_malloc, malloc, realloc,

heap_space_unused

Documented Library Functions

1-270 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

heap_space_unused

Space unused in specific heap

Synopsis

#include <stdlib.h>

int heap_space_unused(int heap_index);

Description

The heap_space_unused function is an Analog Devices extension to the

ANSI standard.

The heap_space_unused function returns the total amount of free space

for the heap with index heap_index.

Note that calling heap_malloc(heap_index,heap_space_unused(heap_in-

dex)) does not allocate space because each allocated block uses more

memory internally than the requested space. Note also that the free space

in the heap may be fragmented, and thus may not be available in one con-

tiguous block.

Error Conditions

If a heap with heap index heap_index does not exist, this function returns

-1.

Example

#include <stdlib.h>

int free_space;

/* Get amount of free space in heap 1 */

free_space = heap_space_unused(1);

CrossCore Embedded Studio 1.1 1-271

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

See Also

calloc, free,heap_calloc, heap_free, heap_init, heap_install, heap_lookup,

heap_malloc, heap_realloc, malloc, realloc, space_unused

Documented Library Functions

1-272 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

heap_switch

Change the default heap at runtime

Synopsis

#include <stdlib.h>

int heap_switch (int heap_index);

Description

The heap_switch function changes the default heap (as used by heap allo-

cation functions malloc, calloc, realloc and free). The function returns

the heapid of the previous default heap.

The function does not check the validity of the heap index. If the heap

index is invalid, then subsequent operations on the default heap (using the

functions malloc, calloc, realloc and space_unused, or using the C++

new operator) will return an error.

For more information on multiple run-time heaps, see the section “Using

Multiple Heaps” in Chapter 1 of the C/C++ Compiler Manual for SHARC

Processors.

The heap_switch function is not available in multithreaded

environments.

Error Conditions

None.

Example

#include <stdlib.h>

#include <stdio.h>

#define HEAP1_USERID 1

CrossCore Embedded Studio 1.1 1-273

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

#define HEAP1_SIZE 1024

int heap1[HEAP1_SIZE];

int heap1_id;

char *pbuf;

/* Initialize */

heap1_id = heap_install (heap1, sizeof(heap1), HEAP1_USERID);

/* Make heap1 the default heap */

heap_switch (heap1_id);

/* Allocate a buffer from heap1 */

pbuf = malloc (32);

if (pbuf == NULL) {

printf ("Unable to allocate buffer\n");

exit (EXIT_FAILURE);

} else {

printf("Allocated buffer from heap1 at %p\n", pbuf);

}

See Also

calloc, free, malloc, realloc

Documented Library Functions

1-274 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

idivfx

Division of fixed-point by fixed-point to give integer result

Synopsis

#include <stdfix.h>

int idivi(fract numer, fract denom);

long int idivlr(long fract numer, long fract denom);

unsigned int idivur(unsigned fract numer, unsigned fract denom);

unsigned long int idivulr(unsigned long fract numer,

unsigned long fract denom);

Description

Given a fixed-point numerator and denominator, the idivfx family of

functions computes the quotient and returns the closest integer value to

the result.

Error Conditions

The idivfx function has undefined behavior if the denominator is zero.

Example

#include <stdfix.h>

unsigned long int ulquo;

ulquo = idivulr(0.5ulr, 0.125ulr); /* ulquo == 4 */

See Also

div, divifx, fxdivi, ldiv, lldiv

CrossCore Embedded Studio 1.1 1-275

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

instrprof_request_flush

Flush the instrumented profiling data to the host

Synopsis

#include <instrprof.h>

void instrprof_request_flush(void);

Description

The instrprof_request_flush function attempts to flush any buffered

instrumented profiling data to the host computer.

The flush occurs immediately if file I/O operations are allowed. (File I/O

operations cannot be executed from interrupt handlers or from unsched-

uled regions in a multi-threaded application.) If the flush cannot occur

immediately, it occurs the next time a profiled function is called, or

returned from when file I/O operations are allowed.

Do not include the header file instrprof.h or reference the func-

tion instrprof_request_flush in an application that is not built

with instrumented profiling enabled.

For more information, see the section “-p” in the C/C++ Compiler

Manual for SHARC Processors. You can guard such code using the

preprocessor macro _INSTRUMENTED_PROFILING. Note that the com-

piler only defines this macro when instrumented profiling is

enabled.

Flushing data to the host is a cycle-intensive operation. Consider carefully

when and where to call this function within your application. For more

information, see “Profiling With Instrumented Code” in Chapter 2 of the

C/C++ Compiler Manual for SHARC Processors.

Documented Library Functions

1-276 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

Error Conditions

None.

Example

#if defined (_INSTRUMENTED_PROFILING)

#include <instrprof.h>

#endif

extern void do_something(void);

int main(void) {

do_something();

#if defined(_INSTRUMENTED_PROFILING)

instrprof_request_flush();

#endif

}

CrossCore Embedded Studio 1.1 1-277

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

ioctl

Apply a control operation to a file descriptor

Synopsis

#include <stdio.h>

int ioctl(int fildes, int cmd, ...);

Description

The ioctl function applies command cmd to file descriptor fildes, along

with any specified arguments for cmd. The file descriptor must be a value

returned by invoking the fileno function upon some open stream fp.

The ioctl function is delegated to the device driver upon which stream fp

was opened. The command cmd, and any provided arguments, are specific

to the device driver; each device driver may interpret commands and argu-

ments differently.

Error Conditions

The ioctl function returns -1 if the operation is not recognized by the

underlying device driver. Other return values are specific to the device

driver’s interpretation of the command.

Example

#include <stdio.h>

int apply_control_cmd(FILE *fp, int cmd, int val) {

int fildes = fileno(fp);

return ioctl(fildes, cmd, val);

}

See Also

fopen, fileno

Documented Library Functions

1-278 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

isalnum

Detect alphanumeric character

Synopsis

#include <ctype.h>

int isalnum (int c);

Description

The isalnum function determines if the argument is an alphanumeric

character (A-Z, a-z, or 0-9). If the argument is not alphanumeric, the

isalnum function returns a zero. If the argument is alphanumeric, isalnum

returns a non-zero value.

Error Conditions

None.

Example

#include <ctype.h>

int ch;

for (ch = 0; ch <= 0x7f; ch++) {

printf ("%#04x", ch);

printf ("%3s", isalnum (ch) ? "alphanumeric" : "");

putchar ('\n');

}

See Also

isalpha, isdigit

CrossCore Embedded Studio 1.1 1-279

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

isalpha

Detect alphabetic character

Synopsis

#include <ctype.h>

int isalpha (int c);

Description

The isalpha function determines if the argument is an alphabetic character

(A-Z or a-z). If the argument is not alphabetic, isalpha returns a zero. If

the argument is alphabetic, isalpha returns a non-zero value.

Error Conditions

None.

Example

#include <ctype.h>

int ch;

for (ch = 0; ch <= 0x7f; ch++) {

printf ("%#04x", ch);

printf ("%2s", isalpha (ch) ? "alphabetic" : "");

putchar ('\n');

}

See Also

isalnum, isdigit

Documented Library Functions

1-280 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

iscntrl

Detect control character

Synopsis

#include <ctype.h>

int iscntrl (int c);

Description

The iscntrl function determines if the argument is a control character

(0x00-0x1F or 0x7F). If the argument is not a control character, iscntrl

returns a zero. If the argument is a control character, iscntrl returns a

non-zero value.

Error Conditions

None.

Example

#include <ctype.h>

int ch;

for (ch = 0; ch <= 0x7f; ch++) {

printf ("%#04x", ch);

printf ("%2s", iscntrl (ch) ? "control" : "");

putchar ('\n');

}

See Also

isalnum, isgraph

CrossCore Embedded Studio 1.1 1-281

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

isdigit

Detect decimal digit

Synopsis

#include <ctype.h>

int isdigit (int c);

Description

The isdigit function determines if the argument c is a decimal digit (0-9).

If the argument is not a digit, isdigit returns a zero. If the argument is a

digit, isdigit returns a non-zero value.

Error Conditions

None.

Example

#include <ctype.h>

int ch;

for (ch = 0; ch <= 0x7f; ch++) {

printf ("%#04x", ch);

printf ("%2s", isdigit (ch) ? "digit" : "");

putchar ('\n');

}

See Also

isalnum, isalpha, isdigit

Documented Library Functions

1-282 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

isgraph

Detect printable character, not including white space

Synopsis

#include <ctype.h>

int isgraph (int c);

Description

The isgraph function determines if the argument is a printable character,

not including a white space (0x21-0x7e). If the argument is not a printable

character, isgraph returns a zero. If the argument is a printable character,

isgraph returns a non-zero value.

Error Conditions

None.

Example

#include <ctype.h>

int ch;

for (ch = 0; ch <= 0x7f; ch++) {

printf ("%#04x", ch);

printf ("%2s", isgraph (ch) ? "graph" : "");

putchar ('\n');

}

See Also

isalnum, iscntrl, isprint

CrossCore Embedded Studio 1.1 1-283

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

isinf

Test for infinity

Synopsis

#include <math.h>

int isinff(float x);

int isinf(double x);

int isinfd(long double x);

Description

The isinf functions are an Analog Devices extension to the ANSI standard.

The isinf functions return a zero if the argument x is not set to the IEEE

constant for +Infinity or -Infinity; otherwise, the functions return a

non-zero value.

Error Conditions

None.

Example

#include <math.h>

static long val[5] = {

0x7F7FFFFF, /* FLT_MAX */

0x7F800000, /* Inf */

0xFF800000, /* -Inf */

0x7F808080, /* NaN */

0xFF808080, /* NaN */

};

float *pval = (float *)(&val);

int m;

Documented Library Functions

1-284 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

m = isinf (pval[0]); /* m set to zero */

m = isinf (pval[1]); /* m set to non-zero */

m = isinf (pval[2]); /* m set to non-zero */

m = isinf (pval[3]); /* m set to zero */

m = isinf (pval[4]); /* m set to zero */

See Also

isnan

CrossCore Embedded Studio 1.1 1-285

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

islower

Detect lowercase character

Synopsis

#include <ctype.h>

int islower (int c);

Description

The islower function determines if the argument is a lowercase character

(a-z). If the argument is not lowercase, islower returns a zero. If the argu-

ment is lowercase, islower returns a non-zero value.

Error Conditions

None.

Example

#include <ctype.h>

int ch;

for (ch = 0; ch <= 0x7f; ch++) {

printf ("%#04x", ch);

printf ("%2s", islower (ch) ? "lowercase" : "");

putchar ('\n');

}

See Also

isalpha, isupper

Documented Library Functions

1-286 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

isnan

Test for Not a Number (NaN)

Synopsis

#include <math.h>

int isnanf(float x);

int isnan(double x);

int isnand(long double x);

Description

The isnan functions are an Analog Devices extension to the ANSI

standard.

The isnan functions return a zero if the argument x is not set to an IEEE

NaN (Not a Number); otherwise, the functions return a non-zero value.

Error Conditions

None.

Example

#include <math.h>

static long val[5] = {

0x7F7FFFFF, /* FLT_MAX */

0x7F800000, /* Inf */

0xFF800000, /* -Inf */

0x7F808080, /* NaN */

0xFF808080, /* NaN */

};

float *pval = (float *)(&val);

int m;

CrossCore Embedded Studio 1.1 1-287

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

m = isnanf (pval[0]); /* m set to zero */

m = isnanf (pval[1]); /* m set to zero */

m = isnanf (pval[2]); /* m set to zero */

m = isnanf (pval[3]); /* m set to non-zero */

m = isnanf (pval[4]); /* m set to non-zero */

See Also

isinf

Documented Library Functions

1-288 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

isprint

Detect printable character

Synopsis

#include <ctype.h>

int isprint (int c);

Description

The isprint function determines if the argument is a printable character

(0x20-0x7E). If the argument is not a printable character, isprint returns

a zero. If the argument is a printable character, isprint returns a non-zero

value.

Error Conditions

None.

Example

#include <ctype.h>

int ch;

for (ch = 0; ch <= 0x7f; ch++) {

printf ("%#04x", ch);

printf ("%3s", isprint (ch) ? "printable" : "");

putchar ('\n');

}

See Also

isgraph, isspace

CrossCore Embedded Studio 1.1 1-289

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

ispunct

Detect punctuation character

Synopsis

#include <ctype.h>

int ispunct (int c);

Description

The ispunct function determines if the argument is a punctuation charac-

ter. If the argument is not a punctuation character, ispunct returns a zero.

If the argument is a punctuation character, ispunct returns a non-zero

value.

Error Conditions

None.

Example

#include <ctype.h>

int ch;

for (ch = 0; ch <= 0x7f; ch++) {

printf ("%#04x", ch);

printf ("%3s", ispunct (ch) ? "punctuation" : "");

putchar ('\n');

}

See Also

isalnum

Documented Library Functions

1-290 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

isspace

Detect whitespace character

Synopsis

#include <ctype.h>

int isspace (int c);

Description

The isspace function determines if the argument is a blank whitespace

character (0x09-0x0D or 0x20). This includes space ( ), form feed (\f),

new line (\n), carriage return (\r), horizontal tab (\t) and vertical tab

(\v).

If the argument is not a blank whitespace character, isspace returns a

zero. If the argument is a blank whitespace character, isspace returns a

non-zero value.

Error Conditions

None.

Example

#include <ctype.h>

int ch;

for (ch = 0; ch <= 0x7f; ch++) {

printf ("%#04x", ch);

printf ("%2s", isspace (ch) ? "space" : "");

putchar ('\n');

}

CrossCore Embedded Studio 1.1 1-291

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

See Also

iscntrl, isgraph

Documented Library Functions

1-292 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

isupper

Detect uppercase character

Synopsis

#include <ctype.h>

int isupper (int c);

Description

The isupper function determines if the argument is an uppercase character

(A-Z). If the argument is not an uppercase character, isupper returns a

zero. If the argument is an uppercase character, isupper returns a

non-zero value.

Error Conditions

None.

Example

#include <ctype.h>

int ch;

for (ch = 0; ch <= 0x7f; ch++) {

printf ("%#04x", ch);

printf ("%2s", isupper (ch) ? "uppercase" : "");

putchar ('\n');

}

See Also

isalpha, islower

CrossCore Embedded Studio 1.1 1-293

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

isxdigit

Detect hexadecimal digit

Synopsis

#include <ctype.h>

int isxdigit (int c);

Description

The isxdigit function determines if the argument is a hexadecimal digit

character (A-F, a-f, or 0-9). If the argument is not a hexadecimal digit,

isxdigit returns a zero. If the argument is a hexadecimal digit, isxdigit

returns a non-zero value.

Error Conditions

None.

Example

#include <ctype.h>

int ch;

for (ch = 0; ch <= 0x7f; ch++) {

printf ("%#04x", ch);

printf ("%2s", isxdigit (ch) ? "hexadecimal" : "");

putchar ('\n');

}

See Also

isalnum, isdigit

Documented Library Functions

1-294 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

labs

Absolute value

Synopsis

#include <stdlib.h>

long int labs (long int j);

Description

The labs function returns the absolute value of its integer argument.

Note that labs (LONG_MIN) == LONG_MIN.

Error Conditions

None.

Example

#include <stdlib.h>

long int j;

j = labs (-285128); /* j = 285128 */

See Also

abs, absfx, fabs, llabs

CrossCore Embedded Studio 1.1 1-295

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

lavg

Mean of two values

Synopsis

#include <stdlib.h>

long int lavg (long int value1, long int value2);

Description

The lavg function is an Analog Devices extension to the ANSI standard.

The lavg function adds two arguments and divides the result by two. The

lavg function is a built-in function which is implemented with an

Rn=(Rx+Ry)/2 instruction.

Error Conditions

None.

Example

#include <stdlib.h>

long int i;

i = lavg (10, 8); /* returns 9 */

See Also

abs, avg, llavg

Documented Library Functions

1-296 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

lclip

Clip

Synopsis

#include <stdlib.h>

long int lclip (long int value1, long int value2);

Description

The lclip function is an Analog Devices extension to the ANSI standard.

The lclip function returns the first argument if its absolute value is less

than the absolute value of the second argument; otherwise it returns the

absolute value of its second argument if the first is positive, or minus the

absolute value if the first argument is negative. The lclip function is a

built-in function which is implemented with an Rn = CLIP Rx BY Ry

instruction.

Error Conditions

None.

Example

#include <stdlib.h>

long int i;

i = lclip (10, 8); /* returns 8 */

i = lclip (8, 10); /* returns 8 */

i = lclip (-10, 8); /* returns -8 */

See Also

clip, fclip, llclip

CrossCore Embedded Studio 1.1 1-297

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

lcount_ones

Count one bits in word

Synopsis

#include <stdlib.h>

int lcount_ones (long int value);

Description

The lcount_ones function is an Analog Devices extension to the ANSI

standard.

The lcount_ones function returns the number of one bits in its argument.

Error Conditions

None.

Example

#include <stdlib.h>

long int flags1 = 4095;

long int flags2 = 4096;

int cnt1;

int cnt2;

cnt1 = lcount_ones (flags1); /* returns 12 */

cnt2 = lcount_ones (flags2); /* returns 1 */

See Also

count_ones, llcount_ones

Documented Library Functions

1-298 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

ldexp

Multiply by power of 2

Synopsis

#include <math.h>

float ldexpf (float x, int n);

double ldexp (double x, int n);

long double ldexpd (long double x, int n);

Description

The ldexp functions return the value of the floating-point argument mul-

tiplied by 2n. These functions add the value of n to the exponent of x.

Error Conditions

If the result overflows, the ldexp functions return HUGE_VAL with the

proper sign. If the result underflows, a zero is returned.

Example

#include <math.h>

double y;

float x;

y = ldexp (0.5, 2); /* y = 2.0 */

x = ldexpf (1.0, 2); /* x = 4.0 */

See Also

exp, pow

CrossCore Embedded Studio 1.1 1-299

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

ldiv

Long division

Synopsis

#include <stdlib.h>

ldiv_t ldiv (long int numer, long int denom);

Description

The ldiv function divides numer by denom, and returns a structure of type

ldiv_t. The type ldiv_t is defined as:

typedef struct {

long int quot;

long int rem;

} ldiv_t;

where quot is the quotient of the division and rem is the remainder, such

that if result is of type ldiv_t, then

result.quot * denom + result.rem == numer

Error Conditions

If denom is zero, the behavior of the ldiv function is undefined.

Example

#include <stdlib.h>

ldiv_t result;

result = ldiv (7L, 2L); /* result.quot = 3, result.rem = 1 */

Documented Library Functions

1-300 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

See Also

div, divifx, fmod, fxdivi, idivfx, lldiv

CrossCore Embedded Studio 1.1 1-301

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

llabs

Absolute value

Synopsis

#include <stdlib.h>

long long llabs (long long j);

Description

The llabs function returns the absolute value of its integer argument.

Note that llabs (LLONG_MIN) == LLONG_MIN.

Error Conditions

None.

Example

#include <stdlib.h>

long long j;

j = llabs (-27081970LL); /* j = 27081970 */

See Also

abs, absfx, fabs, labs

Documented Library Functions

1-302 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

llavg

Mean of two values

Synopsis

#include <stdlib.h>

long long llavg (long long value1, long long value2);

Description

The llavg function is an extension to the ISO/IEC 9899:1990 C standard

and the ISO/IEC 9899:1999 C standard.

The llavg function returns the average of the two arguments value1 and

value2.

Error Conditions

None.

Example

#include <stdlib.h>

long long i;

i = llavg (10LL, 8LL); /* returns 9 */

See Also

abs, avg, lavg

CrossCore Embedded Studio 1.1 1-303

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

llclip

Clip

Synopsis

#include <stdlib.h>

long long llclip (long long value1, long long value2);

Description

The llclip function is an extension to the ISO/IEC 9899:1990 C standard

and the ISO/IEC 9899:1999 C standard.

The llclip function returns the first argument if its absolute value is less

than the absolute value of the second argument; otherwise it returns the

absolute value of its second argument if the first is positive, or minus the

absolute value if the first argument is negative.

Error Conditions

None.

Example

#include <stdlib.h>

long long i;

i = llclip (10LL, 8LL); /* returns 8 */

i = llclip (8LL, 10LL); /* returns 8 */

i = llclip (-10LL, 8LL); /* returns -8 */

See Also

clip, fclip, lclip

Documented Library Functions

1-304 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

llcount_ones

Count one bits in long long

Synopsis

#include <stdlib.h>

int llcount_ones (long long value);

Description

The llcount_ones function is an extension to the ISO/IEC 9899:1990 C

standard and the ISO/IEC 9899:1999 C standard.

The llcount_ones function returns the number of one bits in its argument.

Error Conditions

None.

Example

#include <stdlib.h>

long long flags1 = 4095LL;

long long flags2 = 4096LL;

int cnt1;

int cnt2;

cnt1 = llcount_ones (flags1); /* returns 12 */

cnt2 = llcount_ones (flags2); /* returns 1 */

See Also

count_ones, lcount_ones

CrossCore Embedded Studio 1.1 1-305

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

lldiv

Long long division

Synopsis

#include <stdlib.h>

lldiv_t lldiv (long long numer, long long denom);

Description

The lldiv function divides numer by denom, and returns a structure of type

lldiv_t. The type lldiv_t is defined as:

typedef struct {

long long quot;

long long rem;

} lldiv_t;

where quot is the quotient of the division and rem is the remainder, such

that if result is of type lldiv_t, then

result.quot * denom + result.rem == numer

Error Conditions

If denom is zero, the behavior of the lldiv function is undefined.

Example

#include <stdlib.h>

lldiv_t result;

result = lldiv (7LL, 2LL); /* result.quot = 3, result.rem = 1 */

Documented Library Functions

1-306 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

See Also

div, divifx, fmod, fxdivi, idivfx, ldiv

CrossCore Embedded Studio 1.1 1-307

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

llmax

Long long maximum

Synopsis

#include <stdlib.h>

long long llmax (long long value1, long long value2);

Description

The llmax function is an extension to the ISO/IEC 9899:1990 C standard

and the ISO/IEC 9899:1999 C standard.

The llmax function returns the larger of its two arguments.

Error Conditions

None.

Example

#include <stdlib.h>

long long i;

i = llmax (10LL, 8LL); /* returns 10 */

See Also

fmax, fmin, llmin, lmax, lmin, max, min

Documented Library Functions

1-308 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

llmin

Long long minimum

Synopsis

#include <stdlib.h>

long long llmin (long long value1, long long value2);

Description

The llmin function is an extension to the ISO/IEC 9899:1990 C standard

and the ISO/IEC 9899:1999 C standard.

The llmin function returns the smaller of its two arguments.

Error Conditions

None.

Example

#include <stdlib.h>

long long i;

i = llmin (10LL, 8LL); /* returns 8 */

See Also

fmax, fmin, llmax, lmax, lmin, max, min

CrossCore Embedded Studio 1.1 1-309

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

lmax

Long int maximum

Synopsis

#include <stdlib.h>

long int lmax (long int value1, long int value2);

Description

The lmax function is an extension to the ISO/IEC 9899:1990 C standard

and the ISO/IEC 9899:1999 C standard.

The lmax function returns the larger of its two arguments. The lmax func-

tion is a built-in function which is implemented with an Rn = MAX(Rx,Ry)

instruction.

Error Conditions

None.

Example

#include <stdlib.h>

long int i;

i = lmax (10L, 8L); /* returns 10 */

See Also

fmax, fmin, llmax, llmin, lmin, max, min

Documented Library Functions

1-310 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

lmin

Long minimum

Synopsis

#include <stdlib.h>

long int lmin (long int value1, long int value2);

Description

The lmin function is an extension to the ISO/IEC 9899:1990 C standard

and the ISO/IEC 9899:1999 C standard.

The lmin function returns the smaller of its two arguments. The lmin

function is a built-in function which is implemented with an

Rn = MIN(Rx,Ry) instruction.

Error Conditions

None.

Example

#include <stdlib.h>

long int i;

i = lmin (10L, 8L); /* returns 8 */

See Also

fmax, fmin, llmin, llmax, lmax, max, min

CrossCore Embedded Studio 1.1 1-311

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

localeconv

Get pointer for formatting to current locale

Synopsis

#include <locale.h>

struct lconv *localeconv (void);

Description

The localeconv function returns a pointer to an object of type struct

lconv. This pointer is used to set the components of the object with values

used in formatting numeric quantities in the current locale.

With the exception of decimal_point, those members of the structure

with type char* may use “ “ to indicate that a value is not available.

Expected values are strings. Those members with type char may use

CHAR_MAX to indicate that a value is not available. Expected values are

non-negative numbers.

The program may not alter the structure pointed to by the return value

but subsequent calls to localeconv may do so. Also, calls to setlocale

with the category arguments of LC_ALL, LC_MONETARY and LC_NUMERIC may

overwrite the structure.

Table 1-40. Members of the lconv Struct

Member Description

char *currency_symbol Currency symbol applicable to the locale

char *decimal_point Used to format nonmonetary quantities

char *grouping Used to indicate the number of digits in each nonmonetary

grouping

char *int_curr_symbol Used as international currency symbol (ISO 4217:1987)

for that particular locale plus the symbol used to separate

the currency symbol from the monetary quantity

Documented Library Functions

1-312 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

For grouping and non_grouping, an element of CHAR_MAX indicates that no

further grouping will be performed, a 0 indicates that the previous

char *mon_decimal_point Used for decimal point format monetary quantities

char *mon_grouping Used to indicate the number of digits in each monetary

grouping

char *mon_thousands_sep Used to group monetary quantities prior to the decimal

point

char *negative_sign Used to indicate a negative monetary quantity

char *positive_sign Used to indicate a positive monetary quantity

char *thousands_sep Used to group nonmonetary quantities prior to the decimal

point

char frac_digits Number of digits displayed after the decimal point in mon-

etary quantities in other than international format

char int_frac_digits Number of digits displayed after the decimal point in

international monetary quantities

char p_cs_precedes If set to 1, the currency_symbol precedes the positive

monetary quantity. If set to 0, the currency_symbol suc-

ceeds the positive monetary quantity.

char n_cs_precedes If set to 1, the currency_symbol precedes the negative

monetary quantity. If set to 0, the currency_symbol suc-

ceeds the negative monetary quantity.

char n_sign_posn Indicates the positioning of negative_sign for monetary

quantities.

char n_sep_by_space If set to 1, the currency_symbol is separated from the

negative monetary quantity. If set to 0, the curren-

cy_symbol is not separated from the negative monetary

quantity.

char p_sep_by_space If set to 1, the currency_symbol is separated from the

positive monetary quantity. If set to 0, the currency_sym-

bol is not separated from the positive monetary quantity.

Table 1-40. Members of the lconv Struct (Cont’d)

Member Description

CrossCore Embedded Studio 1.1 1-313

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

element should be used to group the remaining digits, and any other inte-

ger value is used as the number of digits in the current grouping.

The definitions of the values for p_sign_posn and n_sign_posn are:

• parentheses surround currency_symbol and quantity

• sign string precedes currency_symbol and quantity

• sign string succeeds currency_symbol and quantity

• sign string immediately precedes currency_symbol

• sign string immediately succeeds currency_symbol

Error Conditions

None.

Example

#include <locale.h>

struct lconv *c_locale;

c_locale = localeconv (); /* Only the C locale is */

/* currently supported */

See Also

setlocale

Documented Library Functions

1-314 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

localtime

Convert calendar time into broken-down time

Synopsis

#include <time.h>

struct tm *localtime(const time_t *t);

Description

The localtime function converts a pointer to a calendar time into a

broken-down time that corresponds to current time zone. A broken-down

time is a structured variable, which is described in time.h. This implemen-

tation of the header file does not support the Daylight Saving flag nor

does it support time zones and, thus, localtime is equivalent to the

gmtime function.

The broken-down time is returned by localtime as a pointer to static

memory, which may be overwritten by a subsequent call to either

localtime, or to gmtime.

Error Conditions

None.

Example

#include <time.h>

#include <stdio.h>

time_t cal_time;

struct tm *tm_ptr;

CrossCore Embedded Studio 1.1 1-315

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

cal_time = time(NULL);

if (cal_time != (time_t) -1) {

tm_ptr = localtime(&cal_time);

printf("The year is %4d\n",1900 + (tm_ptr->tm_year));

}

See Also

asctime, gmtime, mktime, time

Documented Library Functions

1-316 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

log

Natural logarithm

Synopsis

#include <math.h>

float logf (float x);

double log (double x);

long double logd (long double x);

Description

The natural logarithm functions compute the natural (base e) logarithm of

their argument.

Error Conditions

The natural logarithm functions return zero and set errno to EDOM if the

input value is zero or negative.

Example

#include <math.h>

double y;

float x;

y = log (1.0); /* y = 0.0 */

x = logf (2.71828); /* x = 1.0 */

See Also

alog, exp, log10

CrossCore Embedded Studio 1.1 1-317

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

log10

Base 10 logarithm

Synopsis

#include <math.h>

float log10f (float x);

double log10 (double x);

long double log10d (long double x);

Description

The log10 functions produce the base 10 logarithm of their argument.

Error Conditions

The log10 functions indicate a domain error (set errno to EDOM) and

return zero if the input is zero or negative.

Example

#include <math.h>

double y;

float x;

y = log10 (100.0); /* y = 2.0 */

x = log10f (10.0); /* x = 1.0 */

See Also

alog, log, pow

Documented Library Functions

1-318 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

longjmp

Second return from setjmp

Synopsis

#include <setjmp.h>

void longjmp (jmp_buf env, int return_val);

Description

The longjmp function causes the program to execute a second return from

the place where setjmp (env) was called (with the same jmp_buf

argument).

The longjmp function takes as its arguments a jump buffer that contains

the context at the time of the original call to setjmp. It also takes an inte-

ger, return_val, which setjmp returns if return_val is non-zero.

Otherwise, setjmp returns a 1.

If env was not initialized through a previous call to setjmp or the function

that called setjmp has since returned, the behavior is undefined.

The use of setjmp and longjmp (or similar functions which do not

follow conventional C/C++ flow control) may produce unexpected

results when the application is compiled with optimizations

enabled under certain circumstances. Functions that call setjmp or

longjmp are optimized by the compiler with the assumption that all

variables referenced may be modified by any functions that are

called. This assumption ensures that it is safe to use setjmp and

longjmp with optimizations enabled, though it does mean that it is

dangerous to conceal from the optimizer that a call to setjmp or

longjmp is being made, for example by calling through a function

pointer.

CrossCore Embedded Studio 1.1 1-319

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

Error Conditions

None.

Example

#include <setjmp.h>

#include <stdio.h>

#include <errno.h>

#include <stdlib.h>

jmp_buf env;

int res;

void func (void);

main() {

if ((res = setjmp(env)) != 0) {

printf ("Problem %d reported by func ()\n", res);

exit (EXIT_FAILURE);

}

func();

}

void func (void) {

if (errno != 0) {

longjmp (env, errno);

}

See Also

setjmp

Documented Library Functions

1-320 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

malloc

Allocate memory

Synopsis

#include <stdlib.h>

void *malloc (size_t size);

Description

The malloc function returns a pointer to a block of memory of length

size. The block of memory is uninitialized.

The object is allocated from the current heap, which is the default heap

unless heap_switch has been called to change the current heap to an alter-

nate heap.

Error Conditions

The malloc function returns a null pointer if it is unable to allocate the

requested memory.

Example

#include <stdlib.h>

int *ptr;

size_t sz = 10 * sizeof(int);

ptr = (int *)malloc (sz); /* ptr points to an */

/* array of length 10 */

See Also

calloc, free, heap_calloc, heap_free, heap_malloc, heap_realloc, realloc

CrossCore Embedded Studio 1.1 1-321

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

max

Maximum

Synopsis

#include <stdlib.h>

int max (int value1, int value2);

Description

The max function is an extension to the ISO/IEC 9899:1990 C standard

and the ISO/IEC 9899:1999 C standard.

The max function returns the larger of its two arguments. The max func-

tion is a built-in function which is implemented with an Rn = MAX(Rx,Ry)

instruction.

Error Conditions

None.

Example

#include <stdlib.h>

int i;

i = max (10, 8); /* returns 10 */

See Also

fmax, fmin, llmax, llmin, lmax, lmin, min

Documented Library Functions

1-322 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

memchr

Find first occurrence of character

Synopsis

#include <string.h>

void *memchr (const void *s1, int c, size_t n);

Description

The memchr function compares the range of memory pointed to by s1

with the input character c and returns a pointer to the first occurrence of

c. A null pointer is returned if c does not occur in the first n characters.

Error Conditions

None.

Example

#include <string.h>

char *ptr;

ptr = memchr ("TESTING", 'E', 7);

/* ptr points to the E in TESTING */

See Also

strchr, strrchr

CrossCore Embedded Studio 1.1 1-323

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

memcmp

Compare objects

Synopsis

#include <string.h>

int memcmp (const void *s1, const void *s2, size_t n);

Description

The memcmp function compares the first n characters of the objects

pointed to by s1 and s2. It returns a positive value if the s1 object is lexi-

cally greater than the s2 object, a negative value if the s2 object is lexically

greater than the s1 object, and a zero if the objects are the same.

Error Conditions

None.

Example

#include <string.h>

char *string1 = "ABC";

char *string2 = "BCD";

int result;

result = memcmp (string1, string2, 3); /* result < 0 */

See Also

strcmp, strcoll, strcmp

Documented Library Functions

1-324 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

memcpy

Copy characters from one object to another

Synopsis

#include <string.h>

void *memcpy (void *s1, const void *s2, size_t n);

Description

The memcpy function copies n characters from the object pointed to by s2

into the object pointed to by s1. The behavior of memcpy is undefined if

the two objects overlap. For more information, see memmove.

The memcpy function returns the address of s1.

Error Conditions

None.

Example

#include <string.h>

char *a = "SRC";

char *b = "DEST";

memcpy (b, a, 3); /* b = "SRCT" */

See Also

memmove, strcpy, strncpy

CrossCore Embedded Studio 1.1 1-325

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

memmove

Copy characters between overlapping objects

Synopsis

#include <string.h>

void *memmove (void *s1, const void *s2, size_t n);

Description

The memmove function copies n characters from the object pointed to by

s2 into the object pointed to by s1. The entire object is copied correctly

even if the objects overlap.

The memmove function returns a pointer to s1.

Error Conditions

None.

Example

#include <string.h>

char *ptr, *str = "ABCDE";

ptr = str + 2;

memmove (ptr, str, 3); /* ptr = "ABC", str = "ABABC" */

See Also

memcpy, strcpy, strncpy

Documented Library Functions

1-326 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

memset

Set range of memory to a character

Synopsis

#include <string.h>

void *memset (void *s1, int c, size_t n);

Description

The memset function sets a range of memory to the input character c. The

first n characters of s1 are set to c.

The memset function returns a pointer to s1.

Error Conditions

None.

Example

#include <string.h>

char string1[50];

memset (string1, '\0', 50); /* set string1 to 0 */

See Also

memcpy

CrossCore Embedded Studio 1.1 1-327

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

min

Minimum

Synopsis

#include <stdlib.h>

int min (int value1, int value2);

Description

The min function is an extension to the ISO/IEC 9899:1990 C standard

and the ISO/IEC 9899:1999 C standard.

The min function returns the smaller of its two arguments. The min func-

tion is a built-in function which is implemented with an Rn=MIN(Rx,Ry)

instruction.

Error Conditions

None.

Example

#include <stdlib.h>

int i;

i = min (10, 8); /* returns 8 */

See Also

fmin, llmax, llmin, lmax, lmin, max

Documented Library Functions

1-328 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

mktime

Convert broken-down time into a calendar time

Synopsis

#include <time.h>

time_t mktime(struct tm *tm_ptr);

Description

The mktime function converts a pointer to a broken-down time, which

represents a local date and time, into a calendar time. However, this

implementation of time.h does not support either daylight saving or time

zones and hence this function will interpret the argument as Coordinated

Universal Time (UTC).

A broken-down time is a structured variable which is defined in the

time.h header file as:

struct tm {

int tm_sec; /* seconds after the minute [0,61] */

int tm_min; /* minutes after the hour [0,59] */

int tm_hour; /* hours after midnight [0,23] */

int tm_mday; /* day of the month [1,31] */

int tm_mon; /* months since January [0,11] */

int tm_year; /* years since 1900 */

int tm_wday; /* days since Sunday [0, 6] */

int tm_yday; /* days since January 1st [0,365] */

int tm_isdst; /* Daylight Saving flag */

};

The various components of the broken-down time are not restricted to the

ranges indicated above. The mktime function calculates the calendar time

from the specified values of the components (ignoring the initial values of

tm_wday and tm_yday), and then “normalizes” the broken-down time forc-

ing each component into its defined range.

CrossCore Embedded Studio 1.1 1-329

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

If the component tm_isdst is zero, then the mktime function assumes that

daylight saving is not in effect for the specified time. If the component is

set to a positive value, then the function assumes that daylight saving is in

effect for the specified time and will make the appropriate adjustment to

the broken-down time. If the component is negative, the mktime function

should attempt to determine whether daylight saving is in effect for the

specified time but because neither time zones nor daylight saving are sup-

ported, the effect will be as if tm_isdst were set to zero.

Error Conditions

The mktime function returns the value ((time_t) -1) if the calendar time

cannot be represented.

Example

#include <time.h>

#include <stdio.h>

static const char *wday[] = {"Sun","Mon","Tue","Wed",

"Thu","Fri","Sat","???"};

struct tm tm_time = {0,0,0,0,0,0,0,0,0};

tm_time.tm_year = 2000 - 1900;

tm_time.tm_mday = 1;

if (mktime(&tm_time) == -1)

tm_time.tm_wday = 7;

printf("%4d started on a %s\n",

1900 + tm_time.tm_year,

wday[tm_time.tm_wday]);

Documented Library Functions

1-330 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

See Also

gmtime, localtime, time

CrossCore Embedded Studio 1.1 1-331

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

modf

Separate integral and fractional parts

Synopsis

#include <math.h>

float modff (float x, float *intptr);

double modf (double x, double *intptr);

long double modfd (long double x, long double *intptr);

Description

The modf functions separate the first argument into integral and frac-

tional portions. The fractional portion is returned and the integral portion

is stored in the object pointed to by intptr. The integral and fractional

portions have the same sign as the input.

Error Conditions

None.

Example

#include <math.h>

double y, n;

float m, p;

y = modf (-12.345, &n); /* y = -0.345, n = -12.0 */

m = modff (11.75, &p); /* m = 0.75, p = 11.0 */

See Also

frexp

Documented Library Functions

1-332 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

mulifx

Multiplication of integer by fixed-point to give integer result

Synopsis

#include <stdfix.h>

int mulir(int a, fract b);

long int mulilr(long int a, long fract b);

unsigned int muliur(unsigned int a, unsigned fract b);

unsigned long int muliulr(unsigned long int a,

unsigned long fract b);

Description

Given an integer and a fixed-point value, the mulifx family of functions

computes the product and returns the closest integer value to the result.

Error Conditions

None.

Example

#include <stdfix.h>

unsigned long int ulprod;

ulprod = muliulr(128, 0.125ulr); /* ulquo == 16 */

See Also

No related functions.

CrossCore Embedded Studio 1.1 1-333

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

perror

Print an error message on standard error stream

Synopsis

#include <stdio.h>

void perror(const char *s);

Description

The perror function is used to output an error message to the standard

stream stderr.

If the string s is not a null pointer and if the first character addressed by s

is not a null character, then the function will output the string s followed

by the character sequence ": ". The function will then print the message

that is associated with the current value of errno. Note that the message

"no error" is used if the value of errno is zero.

Error Conditions

None.

Example

#include <stdio.h>

#include <math.h>

#include <errno.h>

float x;

x = acosf (1234.5); /* domain of acosf is [-1.0,1.0] */;

if (errno != 0)

perror("acosf failure");

Documented Library Functions

1-334 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

See Also

strerror

CrossCore Embedded Studio 1.1 1-335

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

pgo_hw_request_flush

Request a flush to the host of the data gathered through profile-guided

optimization on hardware

Synopsis

#include <pgo_hw.h>

void pgo_hw_request_flush(void);

Description

The pgo_hw_request_flush function requests that the runtime support for

profile-guided optimization on hardware should write gathered data to the

host computer. The flush occurs the next time the profile-guided optimi-

zation on hardware run-time support attempts to record data, as long as

file I/O operations are allowed. (File I/O operations cannot be executed

from interrupt handlers or when in an unscheduled region in a

multi-threaded application.)

Do not include the header file pgo_hw.h or reference the function

pgo_hw_request_flush in an application not built for pro-

file-guided optimization on hardware. You can guard such code

using the preprocessor macro _PGO_HW; the compiler only defines

this macro when profile-guided optimization for hardware is

enabled.

For more information, see “-pguide” and “-prof-hw” in Chapter 1

of the C/C++ Compiler Manual for SHARC Processors.

Flushing data to the host is a cycle-intensive operation. Consider carefully

when and where to call this function within your application.

For more information, see “Profile Guided Optimization and Code Cov-

erage” in Chapter 2 of the C/C++ Compiler Manual for SHARC Processors.

Documented Library Functions

1-336 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

Error Conditions

None.

Example

#if defined (_PGO_HW)

#include <pgo_hw.h>

#endif

extern void do_something(void);

int main(void) {

do_something();

#if defined(_PGO_HW)

pgo_hw_request_flush();

#endif

}

CrossCore Embedded Studio 1.1 1-337

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

pow

Raise to a power

Synopsis

#include <math.h>

float powf (float x, float y);

double pow (double x, double y);

long double powd (long double x, long double y);

Description

The power functions compute the value of the first argument raised to the

power of the second argument.

Error Conditions

A domain error occurs if the first argument is negative and the second

argument cannot be represented as an integer. If the first argument is zero,

the second argument is less than or equal to zero and the result cannot be

represented, zero is returned.

Example

#include <math.h>

double z;

float x;

z = pow (4.0, 2.0); /* z = 16.0 */

x = powf (4.0, 2.0); /* x = 16.0 */

See Also

exp, ldexp

Documented Library Functions

1-338 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

printf

Print formatted output

Synopsis

#include <stdio.h>

int printf(const char *format, /* args*/ ...);

Description

The printf function places output on the standard output stream stdout

in a form specified by format. The printf function is equivalent to fprintf

with the stdout passed as the first argument. The argument

format contains a set of conversion specifiers, directives, and ordinary

characters that are used to control how the data is formatted. Refer to

fprintf (on page 1-217) for a description of the valid format specifiers.

The printf function returns the number of characters transmitted.

Error Conditions

If the printf function is unsuccessful, a negative value is returned.

Example

#include <stdio.h>

void printf_example(void)

{

int arg = 255;

/* Output will be "hex:ff, octal:377, integer:255" */

printf("hex:%x, octal:%o, integer:%d\n", arg, arg, arg);

}

CrossCore Embedded Studio 1.1 1-339

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

See Also

fprintf

Documented Library Functions

1-340 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

putc

Put a character on a stream

Synopsis

#include <stdio.h>

int putc(int ch, FILE *stream);

Description

The putc function writes its argument to the output stream pointed to by

stream, after converting ch from an int to an unsigned char.

If the putc function call is successful putc returns its argument ch.

Error Conditions

The stream’s error indicator will be set if the call is unsuccessful, and the

function will return EOF.

Example

#include <stdio.h>

void putc_example(void)

{

/* write the character 'a' to stdout */

if (putc('a', stdout) == EOF)

fprintf(stderr, "putc failed\n");

}

See Also

fputc

CrossCore Embedded Studio 1.1 1-341

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

putchar

Write a character to stdout

Synopsis

#include <stdio.h>

int putchar(int ch);

Description

The putchar function writes its argument to the standard output stream,

after converting ch from an int to an unsigned char. A call to putchar is

equivalent to calling putc(ch, stdout).

If the putchar function call is successful putchar returns its argument ch.

Error Conditions

The stream’s error indicator will be set if the call is unsuccessful, and the

function will return EOF.

Example

#include <stdio.h>

void putchar_example(void)

{

/* write the character 'a' to stdout */

if (putchar('a') == EOF)

fprintf(stderr, "putchar failed\n");

}

See Also

putc

Documented Library Functions

1-342 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

puts

Put a string to stdout

Synopsis

#include <stdio.h>

int puts(const char *s);

Description

The puts function writes the string pointed to by s, followed by a NEWLINE

character, to the standard output stream stdout. The terminating null

character of the string is not written to the stream.

If the function call is successful then the return value is zero or greater.

Error Conditions

The macro EOF is returned if puts was unsuccessful, and the error indica-

tor for stdout will be set.

Example

#include <stdio.h>

void puts_example(void)

{

/* write the string "example" to stdout */

if (puts("example") < 0)

fprintf(stderr, "puts failed\n");

}

See Also

fputs

CrossCore Embedded Studio 1.1 1-343

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

qsort

Quicksort

Synopsis

#include <stdlib.h>

void qsort (void *base, size_t nelem, size_t size,

int (*compar) (const void *, const void *));

Description

The qsort function sorts an array of nelem objects, pointed to by base.

The size of each object is specified by size.

The contents of the array are sorted into ascending order according to a

comparison function pointed to by compar, which is called with two argu-

ments that point to the objects being compared. The function shall return

an integer less than, equal to, or greater than zero if the first argument is

considered to be respectively less than, equal to, or greater than the

second.

If two elements compare as equal, their order in the sorted array is unspec-

ified. The qsort function executes a binary-search operation on a

pre-sorted array, where

•base points to the start of the array.

•nelem is the number of elements in the array.

•size is the size of each element of the array.

•compar is a pointer to a function that is called by qsort to compare

two elements of the array. The function should return a value less

than, equal to, or greater than zero, according to whether the first

argument is less than, equal to, or greater than the second.

Documented Library Functions

1-344 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

Error Conditions

None.

Example

#include <stdlib.h>

float a[10];

int compare_float (const void *a, const void *b)

{

float aval = *(float *)a;

float bval = *(float *)b;

if (aval < bval)

return -1;

else if (aval == bval)

return 0;

else

return 1;

}

qsort (a, sizeof (a)/sizeof (a[0]), sizeof (a[0]),

compare_float);

See Also

bsearch

CrossCore Embedded Studio 1.1 1-345

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

raise

Force a signal

Synopsis

#include <signal.h>

int raise (int sig);

Description

The raise function invokes the function registered for signal sig by func-

tion signal, if any. The sig argument must be one of the signals listed in

signal.

The raise function provides the functionality described in the

ISO/IEC 9899:1999 Standard, and has no impact on the proces-

sor’s interrupt mechanisms. For information on handling

interrupts, refer to the System Run-Time Documentation in the

online help.

Error Conditions

The raise function returns a zero if successful or a non-zero value if sig is

an unrecognized signal value.

Example

#include <signal.h>

raise(SIGABRT); /* equivalent to calling abort() */

See Also

signal

Documented Library Functions

1-346 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

rand

Random number generator

Synopsis

#include <stdlib.h>

int rand (void);

Description

The rand function returns a pseudo-random integer value in the range

[0, 231 – 1].

For this function, the measure of randomness is its periodicity, the num-

ber of values it is likely to generate before repeating a pattern. The output

of the pseudo-random number generator has a period in the order

of 231 – 1.

Error Conditions

None.

Example

#include <stdlib.h>

int i;

i = rand ();

See Also

srand

CrossCore Embedded Studio 1.1 1-347

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

read_extmem

Read external memory

Synopsis

#include <21261.h>

#include <21262.h>

#include <21266.h>

#include <21362.h>

#include <21363.h>

#include <21364.h>

#include <21365.h>

#include <21366.h>

void read_extmem(void *internal_address,

void *external_address,

size_t n);

Description

On ADSP-2126x and some ADSP-2136x processors, it is not possible for

the core to access external memory directly. The read_extmem function

copies data from external to internal memory.

The read_extmem function will transfer n 32-bit words from exter-

nal_address to internal_address.

Error Conditions

None.

Documented Library Functions

1-348 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

Example

#include <21262.h>

int intmem1[100];

int intmem2[100];

/* Place extmem1 in external memory, in the used-defined */

/* section "seg_extmem" */

#pragma section("seg_extmem", DMA_ONLY)

int extmem1[100];

/* Place extmem2 in external memory, in the used-defined */

/* section "seg_extmem" */

#pragma section("seg_extmem", DMA_ONLY)

int extmem2[100];

main() {

/* Transfer 100 words from external memory to internal memory */

read_extmem(intmem1, extmem1, 100);

/* Transfer 100 words from external memory to internal memory */

write_extmem(intmem2, extmem2, 100);

}

This example requires a customized .ldf file containing a section,

seg_extmem, that resides in external memory.

See Also

write_extmem

CrossCore Embedded Studio 1.1 1-349

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

realloc

Change memory allocation

Synopsis

#include <stdlib.h>

void *realloc (void *ptr, size_t size);

Description

The realloc function changes the memory allocation of the object pointed

to by ptr to size. Initial values for the new object are taken from those in

the object pointed to by ptr:

• If the size of the new object is greater than the size of the object

pointed to by ptr, then the values in the newly allocated section are

undefined.

•If ptr is a non-null pointer that was not allocated with one of the

heap functions, the behavior is undefined.

•If ptr is a null pointer, realloc imitates malloc. If size is zero and

ptr is not a null pointer, realloc imitates free.

•If ptr is not a null pointer, then the object is re-allocated from the

heap that the object was originally allocated from.

•If ptr is a null pointer, then the object is allocated from the current

heap, which is the default heap unless heap_switch has been called

to change the current heap to an alternate heap.

Error Conditions

If memory cannot be allocated, ptr remains unchanged and realloc

returns a null pointer.

Documented Library Functions

1-350 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

Example

#include <stdlib.h>

int *ptr;

ptr = (int *)malloc (10); /* allocate array of 10 words */

ptr = (int *)realloc (ptr, 20); /* change size to 20 words */

See Also

calloc, free, heap_calloc, heap_free, heap_malloc, heap_realloc, malloc

CrossCore Embedded Studio 1.1 1-351

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

remove

Remove file

Synopsis

#include <stdio.h>

int remove(const char *filename);

Description

The remove function removes the file whose name is filename. After the

function call, filename will no longer be accessible.

The remove function is delegated to the current default device driver.

The remove function returns zero on successful completion.

Error Conditions

If the remove function is unsuccessful, a non-zero value is returned.

Example

#include <stdio.h>

void remove_example(char *filename)

{

if (remove(filename))

printf("Remove of %s failed\n", filename);

else

printf("File %s removed\n", filename);

}

See Also

rename

Documented Library Functions

1-352 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

rename

Rename a file

Synopsis

#include <stdio.h>

int rename(const char *oldname, const char *newname);

Description

The rename function will establish a new name, using the string newname,

for a file currently known by the string oldname. After a successful rename,

the file will no longer be accessible by oldname.

The rename function is delegated to the current default device driver.

If rename is successful, a value of zero is returned.

Error Conditions

If rename fails, the file named oldname is unaffected and a non-zero value

is returned.

Example

#include <stdio.h>

void rename_file(char *new, char *old)

{

if (rename(old, new))

printf("rename failed for %s\n", old);

else

printf("%s now named %s\n", old, new);

}

CrossCore Embedded Studio 1.1 1-353

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

See Also

remove

Documented Library Functions

1-354 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

rewind

Reset file position indicator in a stream

Synopsis

#include <stdio.h>

void rewind(FILE *stream);

Description

The rewind function sets the file position indicator for stream to the

beginning of the file. This is equivalent to using the fseek routine in the

following manner:

fseek(stream, 0, SEEK_SET);

with the exception that rewind will also clear the error indicator.

Error Conditions

None.

Example

#include <stdio.h>

char buffer[20];

void rewind_example(FILE *fp)

{

/* write "a string" to a file */

fputs("a string", fp);

/* rewind the file to the beginning */

rewind(fp);

/* read back from the file - buffer will be "a string" */

fgets(buffer, sizeof(buffer), fp);

}

CrossCore Embedded Studio 1.1 1-355

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

See Also

fseek

Documented Library Functions

1-356 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

roundfx

Round a fixed-point value to a specified precision

Synopsis

#include <stdfix.h>

short fract roundhr(short fract f, int n);

fract roundr(fract f, int n);

long fract roundlr(long fract f, int n);

unsigned short fract rounduhr(unsigned short fract f, int n);

unsigned fract roundur(unsigned fract f, int n);

unsigned long fract roundulr(unsigned long fract f, int n);

Description

The roundfx family of functions round a fixed-point value to the number

of fractional bits specified by the second argument. The rounding is

round-to-nearest. If the rounded result is out of range of the result type,

the result is saturated to the maximum or minimum fixed-point value. In

addition to the individually-named functions for each fixed-point type, a

type-generic macro roundfx is defined for use in C99 mode. This may be

used with any of the fixed-point types and returns a result of the same type

as its operand.

Error Conditions

None.

Example

#include <stdfix.h>

long fract f;

f = roundulr(0x12345678p-32ulr, 16); /* f == 0x12340000ulr */

f = roundfx(0x12345678p-32ulr, 16); /* f == 0x12340000ulr */

CrossCore Embedded Studio 1.1 1-357

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

See Also

No related functions.

Documented Library Functions

1-358 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

scanf

Convert formatted input from stdin

Synopsis

#include <stdio.h>

int scanf(const char *format, /* args */...);

Description

The scanf function reads from the standard input stream stdin, interprets

the inputs according to format and stores the results of the conversions in

its arguments. The string pointed to by format contains the control for-

mat for the input with the arguments that follow being pointers to the

locations where the converted results are to be written to.

The scanf function is equivalent to calling fscanf with stdin as its first

argument. For details on the control format string refer to fscanf.

The scanf function returns number of successful conversions performed.

Error Conditions

The scanf function will return EOF if it encounters an error before any con-

versions are performed.

Example

#include <stdio.h>

void scanf_example(void)

{

short int day, month, year;

char string[20];

/* Scan a string from standard input */

CrossCore Embedded Studio 1.1 1-359

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

scanf ("%s", string);

/* Scan a date with any separator, eg, 1-1-2006 or 1/1/2006 */

scanf ("%hd%*c%hd%*c%hd", &day, &month, &year);

}

See Also

fscanf

Documented Library Functions

1-360 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

setbuf

Specify full buffering for a stream

Synopsis

#include <stdio.h>

void setbuf(FILE *stream, char* buf);

Description

The setbuf function results in the array pointed to by buf being used to

buffer the stream pointed to by stream instead of an automatically allo-

cated buffer. The setbuf function may be used only after the stream

pointed to by stream is opened but before it is read or written to. Note

that the buffer provided must be of size BUFSIZ as defined in the stdio.h

header.

When the buffer contains data for a text stream (either input data

or output data), the information is held in the form of 8-bit charac-

ters that are packed into 32-bit memory locations. Due to internal

mechanisms used to unpack and pack this data, the I/O buffer

must not reside at a memory location greater than the address

0x3fffffff.

If buf is the NULL pointer, the input/output will be completely unbuffered.

Error Conditions

None.

CrossCore Embedded Studio 1.1 1-361

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

Example

#include <stdio.h>

#include <stdlib.h>

void* allocate_buffer_from_heap(FILE* fp)

{

/* Allocate a buffer from the heap for the file pointer */

void* buf = malloc(BUFSIZ);

if (buf != NULL)

setbuf(fp, buf);

return buf;

}

See Also

setvbuf

Documented Library Functions

1-362 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

setjmp

Define a run-time label

Synopsis

#include <setjmp.h>

int setjmp (jmp_buf env);

Description

The setjmp function saves the calling environment in the jmp_buf argu-

ment. The effect of the call is to declare a run-time label that can be

jumped to via a subsequent call to longjmp.

When setjmp is called, it immediately returns with a result of zero to indi-

cate that the environment has been saved in the jmp_buf argument. If, at

some later point, longjmp is called with the same jmp_buf argument, long-

jmp restores the environment from the argument. The execution is then

resumed at the statement immediately following the corresponding call to

setjmp. The effect is as if the call to setjmp has returned for a second time

but this time the function returns a non-zero result.

The effect of calling longjmp is undefined if the function that called

setjmp has returned in the interim.

The use of setjmp and longjmp (or similar functions which do not

follow conventional C/C++ flow control) may produce unexpected

results when the application is compiled with optimizations

enabled under certain circumstances. Functions that call setjmp or

longjmp are optimized by the compiler with the assumption that all

variables referenced may be modified by any functions that are

called. This assumption ensures that it is safe to use setjmp and

longjmp with optimizations enabled, though it does mean that it is

dangerous to conceal from the optimizer that a call to setjmp or

longjmp is being made, for example by calling through a function

pointer.

CrossCore Embedded Studio 1.1 1-363

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

Error Conditions

None.

Example

See longjmp for an example.

See Also

longjmp

Documented Library Functions

1-364 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

setlocale

Set the current locale

Synopsis

#include <locale.h>

char *setlocale (int category, const char *locale);

Description

The setlocale function uses the parameters category and locale to select a

current locale. The possible values for the category argument are those

macros defined in locale.h beginning with “LC_”. The only locale argu-

ment supported at this time is the “C” locale. If a null pointer is used for

the locale argument, setlocale returns a pointer to a string which is the

current locale for the given category argument. A subsequent call to

setlocale with the same category argument and the string supplied by

the previous setlocale call returns the locale to its original status. The

string pointed to may not be altered by the program but may be overwrit-

ten by subsequent setlocale calls.

Error Conditions

None.

Example

#include <locale.h>

setlocale (LC_ALL, "C");

/* sets the locale to the "C" locale */

See Also

localeconv

CrossCore Embedded Studio 1.1 1-365

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

setvbuf

Specify buffering for a stream

Synopsis

#include <stdio.h>

int setvbuf(FILE *stream, char *buf, int type, size_t size);

Description

The setvbuf function may be used after a stream has been opened but

before it is read or written to. The kind of buffering that is to be used is

specified by the type argument. The valid values for type are detailed in

the following table.

If buf is not the NULL pointer, the array it points to will be used for buffer-

ing, instead of an automatically allocated buffer. Note that if buf is

non-NULL then you must ensure that the associated storage continues to be

available until you close the stream identified by stream. The size argu-

ment specifies the size of the buffer required. If input/output is

unbuffered, the buf and size arguments are ignored.

When the buffer contains data for a text stream (either input data

or output data), the information is held in the form of 8-bit charac-

ters that are packed into 32-bit memory locations. Due to internal

Type Effect

_IOFBF Use full buffering for output. Only output to the host system when

the buffer is full, or when the stream is flushed or closed, or when a

file positioning operation intervenes.

_IOLBF Use line buffering. The buffer will be flushed whenever a NEWLINE is

written, as well as when the buffer is full, or when input is

requested.

_IONBF Do not use any buffering at all.

Documented Library Functions

1-366 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

mechanisms used to unpack and pack this data, the I/O buffer

must not reside at a memory location greater than the address

0x3fffffff.

If buf is the NULL pointer, buffering is enabled and a buffer of size size

will be automatically generated.

The setvbuf function returns zero when successful.

Error Conditions

The setvbuf function will return a non-zero value if either an invalid value

is given for type, or if the stream has already been used to read or write

data, or if an I/O buffer could not be allocated.

Example

#include <stdio.h>

void line_buffer_stderr(void)

{

/* stderr is not buffered - set to use line buffering */

setvbuf (stderr,NULL,_IOLBF,BUFSIZ);

}

See Also

setbuf

CrossCore Embedded Studio 1.1 1-367

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

signal

Define signal handling

Synopsis

#include <signal.h>

void (*signal (int sig, void (*func)(int))) (int);

Description

The signal function determines how to handle a signal that is triggered by

the raise or abort functions. The specified function func can be associated

with one of the sig values listed in Table 1-41.

The function is not thread-safe.

Despite the interpretations of the sig values listed in Table 1-41,

the signal function has no effect on the processor’s interrupt mech-

anism. Any function registered via the signal function will only be

invoked if done so explicitly, via the function abort or the function

raise. For information on handling processor interrupts, see the

System Run-Time Documentation in the online help.

Table 1-41. Valid Values for Parameter sig

Sig Value Meaning, according to ISO/IEC 9899:1999 Standard

SIGTERM Request for program termination.

SIGABRT Program is terminating abnormally.

SIGFPE Arithmetic operation was erroneous, e.g. division by zero.

SIGILL Illegal instruction, or equivalent.

SIGINT Request for interactive attention.

SIGSEGV Access to invalid memory.

Documented Library Functions

1-368 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

The func parameter may be one of the values listed in Table 1-42, instead

of a pointer to a function.

Return Value

The signal function returns the value of the previously installed signal or

signal handler action.

Error Conditions

The signal function returns SIG_ERR and sets errno to SIG_ERR if it does

not recognize the requested signal.

Example

#include <signal.h>

signal (SIGABRT, abort_handler); /* enable abort signal */

signal (SIGABRT, SIG_IGN); /* disable abort signal */

See Also

abort, raise

Table 1-42. Additional Valid Values for Parameter func

func Value Meaning

SIG_DFL Default behavior: do nothing if the signal is triggered by raise or abort.

SIG_ERR An error occurred.

SIG_IGN Ignore the signal if triggered by raise or abort.

CrossCore Embedded Studio 1.1 1-369

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

sin

Sine

Synopsis

#include <math.h>

float sinf (float x);

double sin (double x);

long double sind (long double x);

Description

The sin functions return the sine of x. The input is interpreted as radians;

the output is in the range [-1, 1].

Error Conditions

The input argument x for sinf must be in the domain [-1.647e6,

1.647e6] and the input argument for sind must be in the domain

[-8.433e8, 8.433e8]. The functions return zero if x is outside their

domain.

Example

#include <math.h>

double y;

float x;

y = sin (3.14159); /* y = 0.0 */

x = sinf (3.14159); /* x = 0.0 */

See Also

asin, cos

Documented Library Functions

1-370 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

sinh

Hyperbolic sine

Synopsis

#include <math.h>

float sinhf (float x);

double sinh (double x);

long double sinhd (long double x);

Description

The hyperbolic sine functions return the hyperbolic sine of x.

Error Conditions

The input argument x must be in the domain [-89.39, 89.39] for sinhf,

and in the domain [-710.44, 710.44] for sinhd. If the input value is

greater than the function’s domain, then HUGE_VAL is returned, and if the

input value is less than the domain, then -HUGE_VAL is returned.

Example

#include <math.h>

float x;

double y;

x = sinhf ( 1.0); /* x = 1.1752 */

y = sinh (-1.0); /* y = -1.1752 */

See Also

cosh

CrossCore Embedded Studio 1.1 1-371

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

snprintf

Format data into an n-character array

Synopsis

#include <stdio.h>

int snprintf (char *str, size_t n, const char *format, ...);

Description

The snprintf function is a function that is defined in the C99 Standard

(ISO/IEC 9899).

It is similar to the sprintf function in that snprintf formats data accord-

ing to the argument format, and then writes the output to the array str.

The argument format contains a set of conversion specifiers, directives,

and ordinary characters that are used to control how the data is formatted.

Refer to fprintf (on page 1-217) for a description of the valid format

specifiers.

The function differs from sprintf in that no more than n-1 characters are

written to the output array. Any data written beyond the n-1'th character

is discarded. A terminating NUL character is written after the end of the last

character written to the output array unless n is set to zero, in which case

nothing will be written to the output array and the output array may be

represented by the NULL pointer.

The snprintf function returns the number of characters that would have

been written to the output array str if n was sufficiently large. The return

value does not include the terminating null character written to the array.

The output array will contain all of the formatted text if the return value is

not negative and is also less than n.

Documented Library Functions

1-372 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

Error Conditions

The snprintf function returns a negative value if a formatting error

occurred.

Example

#include <stdio.h>

#include <stdlib.h>

extern char *make_filename(char *name, int id)

{

char *filename_template = "%s%d.dat";

char *filename = NULL;

int len = 0;

int r; /* return value from snprintf */

do {

r = snprintf(filename,len,filename_template,name,id);

if (r < 0) /* formatting error? */

abort();

if (r < len) /* was complete string written? */

return filename; /* return with success */

filename = realloc(filename,(len=r+1));

} while (filename != NULL);

abort();

}

See Also

fprintf, sprintf, vsnprintf

CrossCore Embedded Studio 1.1 1-373

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

space_unused

Space unused in heap

Synopsis

#include <stdlib.h>

int space_unused(void);

Description

The space_unused function returns the size of the total amount of free

space for the default heap. Note that calling malloc(space_unused())

does not allocate space because each allocated block uses more memory

internally than the requested space, and also the free space in the heap

may be fragmented, and thus not be available in one contiguous block.

Error Conditions

If there are no heaps, calling this function will return -1.

Example

#include <stdlib.h>

int free_space;

/* Get amount of free space in the heap */

free_space = space_unused();

See Also

calloc, free,heap_calloc, heap_free, heap_init, heap_install, heap_lookup,

heap_malloc, heap_space_unused, malloc, realloc

Documented Library Functions

1-374 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

sprintf

Format data into a character array

Synopsis

#include <stdio.h>

int sprintf (char *str, const char *format, /* args */...);

Description

The sprintf function formats data according to the argument format, and

then writes the output to the array str. The argument format contains a

set of conversion specifiers, directives, and ordinary characters that are

used to control how the data is formatted. Refer to fprintf

(on page 1-217) for a description of the valid format specifiers.

In all respects other than writing to an array rather than a stream the

behavior of sprintf is similar to that of fprintf.

If the sprintf function is successful it will return the number of characters

written in the array, not counting the terminating NULL character.

Error Conditions

The sprintf function returns a negative value if a formatting error

occurred.

Example

#include <stdio.h>

#include <stdlib.h>

char filename[128];

CrossCore Embedded Studio 1.1 1-375

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

extern char *assign_filename(char *name)

{

char *filename_template = "%s.dat";

int r; /* return value from sprintf */

if ((strlen(name)+5) > sizeof(filename))

abort();

r = sprintf(filename, filename_template, name);

if (r < 0) /* sprintf failed */

abort();

return filename; /* return with success */

}

See Also

fprintf, snprintf

Documented Library Functions

1-376 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

sqrt

Square root

Synopsis

#include <math.h>

float sqrtf (float x);

double sqrt (double x);

long double sqrtd (long double x);

Description

The square root functions return the positive square root of x.

Error Conditions

The square root functions return zero for negative input values and set

errno to EDOM to indicate a domain error.

Example

#include <math.h>

double y;

float x;

y = sqrt (2.0); /* y = 1.414..... */

x = sqrtf (2.0); /* x = 1.414..... */

See Also

rsqrt

CrossCore Embedded Studio 1.1 1-377

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

srand

Random number seed

Synopsis

#include <stdlib.h>

void srand (unsigned int seed);

Description

The srand function is used to set the seed value for the rand function.

A particular seed value always produces the same sequence of

pseudo-random numbers.

Error Conditions

None.

Example

#include <stdlib.h>

srand (22);

See Also

rand

Documented Library Functions

1-378 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

sscanf

Convert formatted input in a string

Synopsis

#include <stdio.h>

int sscanf(const char *s, const char *format, /* args */...);

Description

The sscanf function reads from the string s. The function is equivalent to

fscanf with the exception of the string being read from a string rather

than a stream. The behavior of sscanf when reaching the end of the string

equates to fscanf reaching the EOF in a stream. For details on the control

format string, refer to fscanf.

The sscanf function returns the number of items successfully read.

Error Conditions

If the sscanf function is unsuccessful, EOF is returned.

Example

#include <stdio.h>

void sscanf_example(const char *input)

{

short int day, month, year;

char string[20];

/* Scan for a string from "input" */

sscanf (input, "%s", string);

/* Scan a date with any separator, eg, 1-1-2006 or 1/1/2006 */

sscanf (input, "%hd%*c%hd%*c%hd", &day, &month, &year);

}

CrossCore Embedded Studio 1.1 1-379

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

See Also

fscanf

Documented Library Functions

1-380 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

strcat

Concatenate strings

Synopsis

#include <string.h>

char *strcat (char *s1, const char *s2);

Description

The strcat function appends a copy of the null-terminated string pointed

to by s2 to the end of the null-terminated string pointed to by s1. It

returns a pointer to the new s1 string, which is null-terminated. The

behavior of strcat is undefined if the two strings overlap.

Error Conditions

None.

Example

#include <string.h>

char string1[50];

string1[0] = 'A';

string1[1] = 'B';

string1[2] = '\0';

strcat (string1, "CD"); /* new string is "ABCD" */

See Also

strncat

CrossCore Embedded Studio 1.1 1-381

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

strchr

Find first occurrence of character in string

Synopsis

#include <string.h>

char *strchr (const char *s1, int c);

Description

The strchr function returns a pointer to the first location in s1, a null-ter-

minated string, that contains the character c.

Error Conditions

The strchr function returns a null pointer if c is not part of the string.

Example

#include <string.h>

char *ptr1, *ptr2;

ptr1 = "TESTING";

ptr2 = strchr (ptr1, 'E');

/* ptr2 points to the E in TESTING */

See Also

memchr, strrchr

Documented Library Functions

1-382 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

strcmp

Compare strings

Synopsis

#include <string.h>

int strcmp (const char *s1, const char *s2);

Description

The strcmp function lexicographically compares the null-terminated

strings pointed to by s1 and s2. It returns a positive value if the s1 string

is greater than the s2 string, a negative value if the s2 string is greater than

the s1 string, and a zero if the strings are the same.

Error Conditions

None.

Example

#include <string.h>

char string1[50], string2[50];

if (strcmp (string1, string2))

printf ("%s is different than %s \n", string1, string2);

See Also

memchr, strcmp

CrossCore Embedded Studio 1.1 1-383

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

strcoll

Compare strings

Synopsis

#include <string.h>

int strcoll (const char *s1, const char *s2);

Description

The strcoll function compares the string pointed to by s1 with the string

pointed to by s2. The comparison is based on the locale macro, LC_COL-

LATE. Because only the C locale is defined in the ADSP-21xxx run-time

environment, the strcoll function is identical to the strcmp function.

The function returns a positive value if the s1 string is greater than the s2

string, a negative value if the s2 string is greater than the s1 string, and a

zero if the strings are the same.

Error Conditions

None.

Example

#include <string.h>

char string1[50], string2[50];

if (strcoll (string1, string2))

printf ("%s is different than %s \n", string1, string2);

See Also

strcmp, strncmp

Documented Library Functions

1-384 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

strcpy

Copy from one string to another

Synopsis

#include <string.h>

char *strcpy (char *s1, const char *s2);

Description

The strcpy function copies the null-terminated string pointed to by s2

into the space pointed to by s1. Memory allocated for s1 must be large

enough to hold s2, plus one space for the null character ('\0'). The behav-

ior of strcpy is undefined if the two objects overlap or if s1 is not large

enough. The strcpy function returns the new s1.

Error Conditions

None.

Example

#include <string.h>

char string1[50];

strcpy (string1, "SOMEFUN");

/* SOMEFUN is copied into string1 */

See Also

memcpy, memmove, strncpy

CrossCore Embedded Studio 1.1 1-385

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

strcspn

Length of character segment in one string but not the other

Synopsis

#include <string.h>

size_t strcspn (const char *s1, const char *s2);

Description

The strcspn function returns the array index of the first character in s1

which is not in the set of characters pointed to by s2. The order of the

characters in s2 is not significant.

Error Conditions

None.

Example

#include <string.h>

char *ptr1, *ptr2;

size_t len;

ptr1 = "Tried and Tested";

ptr2 = "aeiou";

len = strcspn (ptr1, ptr2); /* len = 2 */

See Also

strlen, strspn

Documented Library Functions

1-386 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

strerror

Get string containing error message

Synopsis

#include <string.h>

char *strerror (int errnum);

Description

The strerror function is called to return a pointer to an error message that

corresponds to the argument errnum. The global variable errno is com-

monly used as the value of errnum, and as errno is generally not supported

by the library, strerror will always return a pointer to the string “There

are no error strings defined!”.

Error Conditions

None.

Example

#include <string.h>

char *ptr1;

ptr1 = strerror (1);

See Also

No related functions.

CrossCore Embedded Studio 1.1 1-387

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

strftime

Format a broken-down time

Synopsis

#include <time.h>

size_t strftime(char *buf,

size_t buf_size,

const char *format,

const struct tm *tm_ptr);

Description

The strftime function formats the broken-down time tm_ptr into the char

array pointed to by buf, under the control of the format string

format. At most, buf_size characters (including the null terminating

character) are written to buf.

In a similar way as for printf, the format string consists of ordinary char-

acters, which are copied unchanged to the char array buf, and zero or

more conversion specifiers. A conversion specifier starts with the character

% and is followed by a character that indicates the form of transformation

required – the supported transformations are given below in Table 1-43.

Note that the strftime function only supports the “C” locale, and this is

reflected in the table.

Table 1-43. Conversion Specifiers Supported by strftime

Conversion Specifier Transformation ISO/IEC 9899

%a abbreviated weekday name yes

%A full weekday name yes

%b abbreviated month name yes

%B full month name yes

Documented Library Functions

1-388 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

%c date and time presentation in the form

of DDD MMM dd hh:mm:ss yyyy

yes

%C century of the year POSIX.2-1992 + ISO C99

%d day of the month (01 - 31)yes

%D date represented as mm/dd/yy POSIX.2-1992 + ISO C99

%e day of the month, padded with a space

character (cf %d)

POSIX.2-1992 + ISO C99

%F date represented as yyyy-mm-dd POSIX.2-1992 + ISO C99

%h abbreviated name of the month (same as

%b)

POSIX.2-1992 + ISO C99

%H hour of the day as a 24-hour clock

(00-23)

yes

%I hour of the day as a 12-hour clock

(00-12)

yes

%j day of the year (001-366)yes

%k hour of the day as a 24-hour clock pad-

ded with a space ( 0-23)

%l hour of the day as a 12-hour clock pad-

ded with a space (0-12)

%m month of the year (01-12)yes

%M minute of the hour (00-59)yes

%n newline character POSIX.2-1992 + ISO C99

%p AM or PM yes

%P am or pm no

%r time presented as either hh:mm:ss AM or

as hh:mm:ss PM

POSIX.2-1992 + ISO C99

%R time presented as hh:mm POSIX.2-1992 + ISO C99

%S second of the minute (00-61)yes

%t tab character POSIX.2-1992 + ISO C99

Table 1-43. Conversion Specifiers Supported by strftime (Cont’d)

Conversion Specifier Transformation ISO/IEC 9899

CrossCore Embedded Studio 1.1 1-389

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

The current implementation of time.h does not support time zones

and, therefore, the %Z specifier does not generate any characters.

The strftime function returns the number of characters (not including the

terminating null character) that have been written to buf.

Error Conditions

The strftime function returns zero if more than buf_size characters are

required to process the format string. In this case, the contents of the array

buf will be indeterminate.

%T time formatted as %H:%M:%S POSIX.2-1992 + ISO C99

%U week number of the year (week starts on

Sunday) (00-53)

yes

%w weekday as a decimal (0-6) (0 if Sunday) yes

%W week number of the year (week starts on

Sunday) (00-53)

yes

%x date represented as mm/dd/yy (same as

%D)

yes

%X time represented as hh:mm:ss yes

%y year without the century (00-99)yes

%Y year with the century (nnnn)yes

%Z the time zone name, or nothing if the

name cannot be determined

yes

%% % character yes

Table 1-43. Conversion Specifiers Supported by strftime (Cont’d)

Conversion Specifier Transformation ISO/IEC 9899

Documented Library Functions

1-390 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

Example

#include <time.h>

#include <stdio.h>

extern void

print_time(time_t tod)

{

char tod_string[100];

strftime(tod_string,

100,

"It is %M min and %S secs after %l o'clock (%p)",

gmtime(&tod));

puts(tod_string);

}

See Also

ctime, gmtime, localtime, mktime

CrossCore Embedded Studio 1.1 1-391

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

strlen

String length

Synopsis

#include <string.h>

size_t strlen (const char *s1);

Description

The strlen function returns the length of the null-terminated string

pointed to by s1 (not including the terminating null character).

Error Conditions

None.

Example

#include <string.h>

size_t len;

len = strlen ("SOMEFUN"); /* len = 7 */

See Also

strcspn, strspn

Documented Library Functions

1-392 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

strncat

Concatenate characters from one string to another

Synopsis

#include <string.h>

char *strncat (char *s1, const char *s2, size_t n);

Description

The strncat function appends a copy of up to n characters in the null-ter-

minated string pointed to by s2 to the end of the null-terminated string

pointed to by s1. It returns a pointer to the new s1 string.

The behavior of strncat is undefined if the two strings overlap. The new

s1 string is terminated with a null character ('\0').

Error Conditions

None.

Example

#include <string.h>

char string1[50], *ptr;

string1[0] = '\0';

strncat (string1, "MOREFUN", 4);

/* string1 equals "MORE" */

See Also

strncat

CrossCore Embedded Studio 1.1 1-393

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

strncmp

Compare characters in strings

Synopsis

#include <string.h>

int strncmp (const char *s1, const char *s2, size_t n);

Description

The strncmp function lexicographically performs the comparison on the

first n characters of the null-terminated strings pointed to by s1 and s2. It

returns a positive value if the s1 string is greater than the s2 string, a neg-

ative value if the s2 string is greater than the s1 string, and a zero if the

strings are the same.

Error Conditions

None.

Example

#include <string.h>

char *ptr1;

ptr1 = "TEST1";

if (strncmp (ptr1, "TEST", 4) == 0)

printf ("%s starts with TEST\n", ptr1);

See Also

memcmp, strcmp

Documented Library Functions

1-394 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

strncpy

Copy characters from one string to another

Synopsis

#include <string.h>

char *strncpy (char *s1, const char *s2, size_t n);

Description

The strncpy function copies up to n characters of the null-terminated

string, starting with element 0, pointed to by s2 into the space pointed to

by s1. If the last character copied from s2 is not a null, the result does not

end with a null. The behavior of strncpy is undefined if the two objects

overlap. The strncpy function returns the new s1.

If the s2 string contains fewer than n characters, the s1 string is padded

with the null character until all n characters have been written.

Error Conditions

None.

Example

#include <string.h>

char string1[50];

strncpy (string1, "MOREFUN", 4);

/* MORE is copied into string1 */

string1[4] = '\0'; /* must null-terminate string1 */

See Also

memcpy, memmove, strcpy

CrossCore Embedded Studio 1.1 1-395

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

strpbrk

Find character match in two strings

Synopsis

#include <string.h>

char *strpbrk (const char *s1, const char *s2);

Description

The strpbrk function returns a pointer to the first character in s1 that is

also found in s2. The string pointed to by s2 is treated as a set of charac-

ters. The order of the characters in the string is not significant.

Error Conditions

In the event that no character in s1 matches any in s2, a null pointer is

returned.

Example

#include <string.h>

char *ptr1, *ptr2, *ptr3;

ptr1 = "TESTING";

ptr2 = "SHOP"

ptr3 = strpbrk (ptr1, ptr2);

/* ptr3 points to the S in TESTING */

See Also

strspn

Documented Library Functions

1-396 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

strrchr

Find last occurrence of character in string

Synopsis

#include <string.h>

char *strrchr (const char *s1, int c);

Description

The strrchr function returns a pointer to the last occurrence of character c

in the null-terminated input string s1.

Error Conditions

The strrchr function returns a null pointer if c is not found.

Example

#include <string.h>

char *ptr1, *ptr2;

ptr1 = "TESTING”;

ptr2 = strrchr (ptr1, 'T');

/* ptr2 points to the second T of TESTING */

See Also

memchr, strchr

CrossCore Embedded Studio 1.1 1-397

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

strspn

Length of segment of characters in both strings

Synopsis

#include <string.h>

size_t strspn (const char *s1, const char *s2);

Description

The strspn function returns the length of the initial segment of s1, which

consists entirely of characters in the string pointed to by s2. The string

pointed to by s2 is treated as a set of characters. The order of the charac-

ters in the string is not significant.

Error Conditions

None.

Example

#include <string.h>

size_t len;

char *ptr1, *ptr2;

ptr1 = "TESTING";

ptr2 = "ERST";

len = strspn (ptr1, ptr2); /* len = 4 */

See Also

strcspn, strlen

Documented Library Functions

1-398 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

strstr

Find string within string

Synopsis

#include <string.h>

char *strstr (const char *s1, const char *s2);

Description

The strstr function returns a pointer to the first occurrence in the string

pointed to by s1 of the characters in the string pointed to by s2. This

excludes the terminating null character in s1.

Error Conditions

If the string is not found, strstr returns a null pointer. If s2 points to a

string of zero length, s1 is returned.

Example

#include <string.h>

char *ptr1, *ptr2;

ptr1 = "TESTING";

ptr2 = strstr (ptr1, "E");

/* ptr2 points to the E in TESTING */

See Also

strchr

CrossCore Embedded Studio 1.1 1-399

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

strtod

Convert string to double

Synopsis

#include <stdlib.h>

double strtod(const char *nptr, char **endptr)

Description

The strtod function extracts a value from the string pointed to by nptr,

and returns the value as a double. The strtod function expects nptr to

point to a string that represents either a decimal floating-point number or

a hexadecimal floating-point number. Either form of number may be pre-

ceded by a sequence of whitespace characters (as determined by the

isspace function) that the function ignores.

A decimal floating-point number has the form:

[sign] [digits] [.digits] [{e|E} [sign] [digits]]

The sign token is optional and is either plus ( + ) or minus ( – ); and dig-

its are one or more decimal digits. The sequence of digits may contain a

decimal point ( . ).

The decimal digits can be followed by an exponent, which consists of an

introductory letter (e or E) and an optionally signed integer. If neither an

exponent part nor a decimal point appears, a decimal point is assumed to

follow the last digit in the string.

The form of a hexadecimal floating-point number is:

[sign] [{0x}|{0X}] [hexdigs] [.hexdigs] [{p|P} [sign]

[digits]]

A hexadecimal floating-point number may start with an optional plus ( + )

or minus ( – ) followed by the hexadecimal prefix 0x or 0X. This character

Documented Library Functions

1-400 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

sequence must be followed by one or more hexadecimal characters that

optionally contain a decimal point ( . ).

The hexadecimal digits are followed by a binary exponent that consists of

the letter p or P, an optional sign, and a non-empty sequence of decimal

digits. The exponent is interpreted as a power of two that is used to scale

the fraction represented by the tokens [hexdigs] [.hexdigs].

The first character that does not fit either form of number stops the scan.

If endptr is not NULL, a pointer to the character that stopped the scan is

stored at the location pointed to by endptr. If no conversion can be per-

formed, the value of nptr is stored at the location pointed to by endptr.

Error Conditions

The strtod function returns a zero if no conversion can be made and a

pointer to the invalid string is stored in the object pointed to by endptr. If

the correct value results in an overflow, a positive or negative (as appropri-

ate) HUGE_VAL is returned. If the correct value results in an underflow, zero

is returned. The ERANGE value is stored in errno in the case of either an

overflow or underflow.

Example

#include <stdlib.h>

char *rem;

double dd;

dd = strtod ("2345.5E4 abc",&rem);

/* dd = 2.3455E+7, rem = " abc" */

dd = strtod ("-0x1.800p+9,123",&rem);

/* dd = -768.0, rem = ",123" */

CrossCore Embedded Studio 1.1 1-401

C/C++ Library Manual for SHARC Processors

C/C++ Run-Time Library

See Also

atof, strtofxfx, strtol, strtoul

Documented Library Functions

1-402 CrossCore Embedded Studio 1.1

C/C++ Library Manual for SHARC Processors

strtofxfx

Convert string to fixed-point

Synopsis

#include <stdfix.h>

short fract strtofxhr(const char *nptr, char **endptr);

fract strtofxr(const char *nptr, char **endptr);

long fract strtofxlr(const char *nptr, char **endptr);

unsigned short fract strtofxuhr(const char *nptr, char **endptr);

unsigned fract strtofxur(const char *nptr, char **endptr);

unsigned long fract strtofxulr(const char *nptr, char **endptr);

Description

The strtofxfx family of functions extracts a value from the string pointed

to by nptr, and returns the value as a fixed-point. The strtofxfx functions

expect nptr to point to a string that represents either a decimal float-

ing-point number or a hexadecimal floating-point number. Either form of

number may be preceded by a sequence of whitespace characters (as deter-

mined by the isspace function) that the function ignores.

A decimal floating-point number has the form:

[sign] [digits] [.digits] [{e|E} [sign] [digits]]

The sign token is optional and is either plus ( + ) or minus ( – ); and

digits are one or more decimal digits. The sequence of digits may contain

a decimal point ( . ).

The decimal digits can be followed by an exponent, which consists of an

introductory letter (e or E) and an optionally signed integer. If neither an

exponent part nor a decimal point appears, a decimal point is assumed to

follow the last digit in the string.

CrossCore Embedded Studio 1.1 1-403