convert_external(3M)convert_external(3M)NAMEconvert_external - convert external binary data formats
SYNOPSIS
cc [ flag ... ] file ... -lsunmath -lm [ library ... ]
#include <sunmath.h>
enum convert_external_arch_t = {
convert_external_sparc, convert_external_pc,
convert_external_vax, convert_external_vaxg,
convert_external_s370, convert_external_cray };
enum convert_external_type_t = {
convert_external_signed,
convert_external_unsigned,
convert_external_float };
enum convert_external_rounding_t = {
convert_external_common = -1,
convert_external_biased = -2,
convert_external_away = -3 };
typedef struct {
enum convert_external_arch_t arch ; /* format architecture */
enum convert_external_type_t type ; /* format type */
int size ; /* format size in 8-bit bytes */
} convert_external_t ;
fp_exception_field_type convert_external(const char *src_p, con‐
vert_external_t src_format, char *dst_p, convert_external_t dst_format,
int rounding, int n);
fp_exception_field_type convert_external_(const char *src_p, const con‐
vert_external_t *src_format_p, char *dst_p, const convert_external_t
*dst_format_p, const int *rounding_p, const int *n_p);
DESCRIPTIONconvert_external() is used in C programs to convert between binary data
on non-SPARC systems and SPARC binary data. The data may be signed
integers, unsigned integers, or floating-point data. convert_exter‐
nal_() is used in Fortran programs (CALL CONVERT_EXTERNAL(...)) for
the same purpose, with all parameters call-by-reference.
The convert_external_t type describes the supported formats; for each
architecture, signed and unsigned integers of sizes 1, 2, 4, 8, or 16
bytes, and floating-point types of sizes 4, 8, 10, 12, or 16 bytes in
size are supported. If an improper size is specified for the source or
destination, no conversion occurs and (1<<fp_division) is returned, an
exception that can't arise otherwise.
Supported architectures and formats include
external_t endian- float*4 float*8 float*10 float*12 float*16
architecture ness format format format format format
sparc big IEEE IEEE none MC68881 IEEE
single double extended quad
pc little IEEE IEEE i80x87 i80960KB IEEE
single double extended extended quad
vax little VAX F VAX D none none VAX H
vaxg little VAX F VAX G none none VAX H
s370 big S/370 S/370 none none S/370
single double extended
cray big none Cray-1 none none Cray-1
single double
Note that MC68000 and SPARC formats are identical big-endian formats;
the Intel PC formats for 8086/8087, 80x86/7, and 80486 are identical
little-endian. Table entries ``none'' represent improper sizes; no
conversion occurs. ``IEEE quad'' refers to the natural big- or little-
endian extension of IEEE single and double precision to a format with
15 exponent bits, one implicit significand bit, and 112 explicit sig‐
nificand bits.
USAGE
excep = convert_external(src_p, src_format, dst_p, dst_format, rounding, n);
excep The function value is an accumulation of all the excep‐
tions encountered during the conversion. If detecting
individual exceptions is important, n should be 1 so that
only one data item is converted at a time.
src_p A pointer to the data to be converted stored as a con‐
tiguous array. The pointer is declared char * to empha‐
size that there are no alignment requirements, although
data being converted to SPARC format for subsequent pro‐
cessing by the same program should be appropriately
aligned.
dst_p A pointer to the converted data stored as a contiguous
array.
src_format
Description of the format of the source data.
dst_format
Description of the format of the destination data.
rounding
The rounding mode to apply to the destination data.
n Number of data items to be converted.
Rounding choices; the first is intended to be satisfactory for almost
all applications:
(int) convert_external_common
integer and unsigned destination formats round toward zero (2.9
rounds to 2, -2.9 rounds to -2),
IEEE floating-point destinations round to nearest unbiased,
VAX floating-point destinations round to nearest biased,
IBM 370 and Cray floating-point destinations round toward zero.
(int) convert_external_biased
to round to nearest biased (for integer destinations, 1.5 rounds
to 2, 2.5 rounds to 3).
(int) convert_external_away
to round away from zero (for integer destinations, 2.1 rounds to
3, -2.1 rounds to -3).
(int) fp_nearest, fp_tozero, fp_positive, fp_negative
to obtain rounding in one of the modes specified in IEEE 754.
After the conversion, if (excep & (1 << fp_invalid)) != 0, then one or
more invalid exceptions occurred; similarly for the other exceptions,
which are defined this way:
fp_invalid
An input argument was an IEEE signaling NaN or a VAX reserved
operand, or an input argument was an infinity and the destina‐
tion was an integer or unsigned type, or a floating-point type
with no infinity representation.
fp_overflow
An input argument was finite and large but could not be repre‐
sented in the destination format with only normal rounding
error; if the destination format is integer or unsigned then
fp_overflow represents integer overflow.
fp_underflow
An input argument was finite and small and could not be repre‐
sented in the destination format with only normal rounding
error. This can only arise with floating-point destinations.
fp_inexact
An input argument was finite but could not be represented
exactly in the destination format.
fp_division
The source or destination formats aren't supported. No conver‐
sions are done.
Note that converting external data to SPARC format, processing on a
SPARC, then converting back to external format will almost never yield
the same results as processing the data entirely on the external sys‐
tem, even if the conversions and processing yield no exceptions on the
SPARC.
EXAMPLES
Generating data on an external system
The following code demonstrates typical Fortran generation of binary
floating-point data on an external system:
REAL A(100)WRITE(9) A
Converting external data to SPARC internal form in C
Suppose the previous binary data file was created on a tape on a Cray
and read on a SPARC system. To convert to IEEE double-precision float‐
ing-point format, but using biased rounding,
#include <sunmath.h>
char datasrc[800];
double datadest[100];
fp_exception_field_type excep;
int rounding;
int i;
convert_external_t src, dest;
/* read the Cray data into the array datasrc somehow, then ... */
src.arch = convert_external_cray;
src.type = convert_external_float;
src.size = 8;
dest.arch = convert_external_sparc;
dest.type = convert_external_float;
dest.size = 8;
rounding = convert_external_biased;
excep = convert_external((char *) datasrc, src, (char *) datadest, dest, rounding, 100);
/*
* usually you aren't interested in inexact exceptions
* and you'd do this
*/
excep &= ~(1 << fp_inexact);
/*
* other exceptions are possible in this example - after the fact,
* you can find out where they happened this way
*/
if (excep != 0) for (i = 0 ; i < 100 ; i++) {
excep = convert_external((char *)&datasrc[8 * i], src, (char *)&datadest[i], dest, rounding, 1);
if (excep != 0) {
/* do something specific about datadest[i] */
}
}
Converting SPARC internal data to external form in Fortran
Suppose data created in a SPARC program is to be read into an IBM PC.
To convert,
#include <floatingpoint.h>
REAL*4 datasrc(100)
REAL*4 datadest(100)
INTEGER excep, convert_external, round
INTEGER src(4), dest(4)
c create datasrc array somehow, then ...
src(1) = convert_external_sparc
src(2) = convert_external_float
src(3) = 4
dest(1) = convert_external_pc
dest(2) = convert_external_float
dest(3) = 4
round = convert_external_common
excep = convert_external(datasrc, src, datadest, dest, round, 100)
c The only exception that can arise is fp_invalid,
c by converting a signaling NaN.
c Now write the data out in a file that an IBM PC can read
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
┌────────────────────┬─────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├────────────────────┼─────────────────┤
│Interface Stability │ Committed │
│MT-Level │ MT-Safe │
└────────────────────┴─────────────────┘
SEE ALSOdd(1M), for reading tapes from foreign systems; xdr(3N), for formatting
arbitrary data structures in a machine-independent fashion.
NOTES
Conversions are performed one at a time by converting a source datum
into an internal format large enough to hold any input exactly, then by
converting the internal data to the destination form. Thus any pair of
source and destination formats is permitted, but efficiency is not as
high as would be the case for programs written to convert from one spe‐
cific format to another.
14 Mar 2009 convert_external(3M)