BRL-CAD
cv.h
Go to the documentation of this file.
1 /* C V . H
2  * BRL-CAD
3  *
4  * Copyright (c) 2004-2014 United States Government as represented by
5  * the U.S. Army Research Laboratory.
6  *
7  * This library is free software; you can redistribute it and/or
8  * modify it under the terms of the GNU Lesser General Public License
9  * version 2.1 as published by the Free Software Foundation.
10  *
11  * This library is distributed in the hope that it will be useful, but
12  * WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14  * Lesser General Public License for more details.
15  *
16  * You should have received a copy of the GNU Lesser General Public
17  * License along with this file; see the file named COPYING for more
18  * information.
19  */
20 
21 #ifndef BU_CV_H
22 #define BU_CV_H
23 
24 #include "common.h"
25 
26 #include <stddef.h> /* for size_t */
27 #include <limits.h> /* for CHAR_MAX */
28 
29 #include "bu/defines.h"
30 
32 
33 /*----------------------------------------------------------------------*/
34 
35 /** @addtogroup conv */
36 /** @{*/
37 
38 /**
39  * Sizes of "network" format data. We use the same convention as the
40  * TCP/IP specification, namely, big-Endian, IEEE format, twos
41  * complement. This is the BRL-CAD external data representation
42  * (XDR). See also the support routines in libbu/xdr.c
43  *
44  */
45 #define SIZEOF_NETWORK_SHORT 2 /* htons(), bu_gshort(), bu_pshort() */
46 #define SIZEOF_NETWORK_LONG 4 /* htonl(), bu_glong(), bu_plong() */
47 #define SIZEOF_NETWORK_FLOAT 4 /* htonf() */
48 #define SIZEOF_NETWORK_DOUBLE 8 /* htond() */
49 
50 /**
51  * provide for 64-bit network/host conversions using ntohl()
52  */
53 #ifndef HAVE_NTOHLL
54 # define ntohll(_val) ((bu_byteorder() == BU_LITTLE_ENDIAN) ? \
55  ((((uint64_t)ntohl((_val))) << 32) + ntohl((_val) >> 32)) : \
56  (_val)) /* sorry pdp-endian */
57 #endif
58 #ifndef HAVE_HTONLL
59 # define htonll(_val) ntohll(_val)
60 #endif
61 
62 
63 #define CV_CHANNEL_MASK 0x00ff
64 #define CV_HOST_MASK 0x0100
65 #define CV_SIGNED_MASK 0x0200
66 #define CV_TYPE_MASK 0x1c00 /* 0001 1100 0000 0000 */
67 #define CV_CONVERT_MASK 0x6000 /* 0110 0000 0000 0000 */
68 
69 #define CV_TYPE_SHIFT 10
70 #define CV_CONVERT_SHIFT 13
71 
72 #define CV_8 0x0400
73 #define CV_16 0x0800
74 #define CV_32 0x0c00
75 #define CV_64 0x1000
76 #define CV_D 0x1400
77 
78 #define CV_CLIP 0x0000
79 #define CV_NORMAL 0x2000
80 #define CV_LIT 0x4000
81 
82 /** deprecated */
83 #define END_NOTSET 0
84 #define END_BIG 1 /* PowerPC/MIPS */
85 #define END_LITTLE 2 /* Intel */
86 #define END_ILL 3 /* PDP-11 */
87 #define END_CRAY 4 /* Old Cray */
88 
89 /** deprecated */
90 #define IND_NOTSET 0
91 #define IND_BIG 1
92 #define IND_LITTLE 2
93 #define IND_ILL 3
94 #define IND_CRAY 4
95 
96 
97 /** @file libbu/convert.c
98  *
99  * Routines to translate data formats. The data formats are:
100  *
101  * \li Host/Network is the data in host format or local format
102  * \li signed/unsigned Is the data signed?
103  * \li char/short/int/long/double
104  * Is the data 8bits, 16bits, 32bits, 64bits
105  * or a double?
106  *
107  * The method of conversion is to convert up to double then back down the
108  * the expected output format.
109  *
110  */
111 
112 /**
113  * convert from one format to another.
114  *
115  * @param in input pointer
116  * @param out output pointer
117  * @param count number of entries to convert
118  * @param size size of output buffer
119  * @param infmt input format
120  * @param outfmt output format
121  *
122  */
123 BU_EXPORT extern size_t bu_cv(void *out, char *outfmt, size_t size, void *in, char *infmt, size_t count);
124 
125 /**
126  * Sets a bit vector after parsing an input string.
127  *
128  * Set up the conversion tables/flags for vert.
129  *
130  * @param in format description.
131  *
132  * @return a 32 bit vector.
133  *
134  * Format description:
135  * [channels][h|n][s|u] c|s|i|l|d|8|16|32|64 [N|C|L]
136  *
137  * @n channels must be null or 1
138  * @n Host | Network
139  * @n signed | unsigned
140  * @n char | short | integer | long | double | number of bits of integer
141  * @n Normalize | Clip | low-order
142  */
143 BU_EXPORT extern int bu_cv_cookie(const char *in);
144 
145 /**
146  * It is always more efficient to handle host data, rather than
147  * network. If host and network formats are the same, and the request
148  * was for network format, modify the cookie to request host format.
149  */
150 BU_EXPORT extern int bu_cv_optimize(int cookie);
151 
152 /**
153  * Returns the number of bytes each "item" of type "cookie" occupies.
154  */
155 BU_EXPORT extern size_t bu_cv_itemlen(int cookie);
156 
157 /**
158  * convert with cookie
159  *
160  * @param in input pointer
161  * @param incookie input format cookie.
162  * @param count number of entries to convert.
163  * @param out output pointer.
164  * @param outcookie output format cookie.
165  * @param size size of output buffer in bytes;
166  *
167  *
168  * A worst case would be: ns16 on vax to ns32
169  @code
170  ns16 -> hs16
171  -> hd
172  -> hs32
173  -> ns32
174  @endcode
175  * The worst case is probably the easiest to deal with because all
176  * steps are done. The more difficult cases are when only a subset of
177  * steps need to be done.
178  *
179  * @par Method:
180  @code
181  HOSTDBL defined as true or false
182  if ! hostother then
183  hostother = (Endian == END_BIG) ? SAME : DIFFERENT;
184  fi
185  if (infmt == double) then
186  if (HOSTDBL == SAME) {
187  inIsHost = host;
188  fi
189  else
190  if (hostother == SAME) {
191  inIsHost = host;
192  fi
193  fi
194  if (outfmt == double) then
195  if (HOSTDBL == SAME) {
196  outIsHost == host;
197  else
198  if (hostother == SAME) {
199  outIsHost = host;
200  fi
201  fi
202  if (infmt == outfmt) {
203  if (inIsHost == outIsHost) {
204  copy(in, out)
205  exit
206  else if (inIsHost == net) {
207  ntoh?(in, out);
208  exit
209  else
210  hton?(in, out);
211  exit
212  fi
213  fi
214 
215  while not done {
216  from = in;
217 
218  if (inIsHost == net) {
219  ntoh?(from, t1);
220  from = t1;
221  fi
222  if (infmt != double) {
223  if (outIsHost == host) {
224  to = out;
225  else
226  to = t2;
227  fi
228  castdbl(from, to);
229  from = to;
230  fi
231 
232  if (outfmt == double) {
233  if (outIsHost == net) {
234  hton?(from, out);
235  fi
236  else
237  if (outIsHost == host) {
238  dblcast(from, out);
239  else
240  dblcast(from, t3);
241  hton?(t3, out);
242  fi
243  fi
244  done
245  @endcode
246  */
247 BU_EXPORT extern size_t bu_cv_w_cookie(void *out, int outcookie, size_t size, void *in, int incookie, size_t count);
248 
249 /**
250  * bu_cv_ntohss
251  *
252  * @brief
253  * Network TO Host Signed Short
254  *
255  * It is assumed that this routine will only be called if there is
256  * real work to do. Ntohs does no checking to see if it is reasonable
257  * to do any conversions.
258  *
259  * @param in generic pointer for input.
260  * @param count number of shorts to be generated.
261  * @param out short pointer for output
262  * @param size number of bytes of space reserved for out.
263  *
264  * @return number of conversions done.
265  */
266 BU_EXPORT extern size_t bu_cv_ntohss(signed short *in, /* FIXME: in/out right? */
267  size_t count,
268  void *out,
269  size_t size);
270 BU_EXPORT extern size_t bu_cv_ntohus(unsigned short *,
271  size_t,
272  void *,
273  size_t);
274 BU_EXPORT extern size_t bu_cv_ntohsl(signed long int *,
275  size_t,
276  void *,
277  size_t);
278 BU_EXPORT extern size_t bu_cv_ntohul(unsigned long int *,
279  size_t,
280  void *,
281  size_t);
282 BU_EXPORT extern size_t bu_cv_htonss(void *,
283  size_t,
284  signed short *,
285  size_t);
286 BU_EXPORT extern size_t bu_cv_htonus(void *,
287  size_t,
288  unsigned short *,
289  size_t);
290 BU_EXPORT extern size_t bu_cv_htonsl(void *,
291  size_t,
292  long *,
293  size_t);
294 BU_EXPORT extern size_t bu_cv_htonul(void *,
295  size_t,
296  unsigned long *,
297  size_t);
298 
299 /** @file libbu/htond.c
300  *
301  * Convert doubles to host/network format.
302  *
303  * Library routines for conversion between the local host 64-bit
304  * ("double precision") representation, and 64-bit IEEE double
305  * precision representation, in "network order", i.e., big-endian, the
306  * MSB in byte [0], on the left.
307  *
308  * As a quick review, the IEEE double precision format is as follows:
309  * sign bit, 11 bits of exponent (bias 1023), and 52 bits of mantissa,
310  * with a hidden leading one (0.1 binary).
311  *
312  * When the exponent is 0, IEEE defines a "denormalized number", which
313  * is not supported here.
314  *
315  * When the exponent is 2047 (all bits set), and:
316  * all mantissa bits are zero,
317  * value is infinity*sign,
318  * mantissa is non-zero, and:
319  * msb of mantissa=0: signaling NAN
320  * msb of mantissa=1: quiet NAN
321  *
322  * Note that neither the input or output buffers need be word aligned,
323  * for greatest flexibility in converting data, even though this
324  * imposes a speed penalty here.
325  *
326  * These subroutines operate on a sequential block of numbers, to save
327  * on subroutine linkage execution costs, and to allow some hope for
328  * vectorization.
329  *
330  * On brain-damaged machines like the SGI 3-D, where type "double"
331  * allocates only 4 bytes of space, these routines *still* return 8
332  * bytes in the IEEE buffer.
333  *
334  */
335 
336 /**
337  * Host to Network Doubles
338  */
339 BU_EXPORT extern void bu_cv_htond(unsigned char *out,
340  const unsigned char *in,
341  size_t count);
342 
343 /**
344  * Network to Host Doubles
345  */
346 BU_EXPORT extern void bu_cv_ntohd(unsigned char *out,
347  const unsigned char *in,
348  size_t count);
349 
350 /** @file libbu/htonf.c
351  *
352  * convert floats to host/network format
353  *
354  * Host to Network Floats + Network to Host Floats.
355  *
356  */
357 
358 /**
359  * Host to Network Floats
360  */
361 BU_EXPORT extern void bu_cv_htonf(unsigned char *out,
362  const unsigned char *in,
363  size_t count);
364 
365 /**
366  * Network to Host Floats
367  */
368 BU_EXPORT extern void bu_cv_ntohf(unsigned char *out,
369  const unsigned char *in,
370  size_t count);
371 
372 
373 /** @file libbu/b64.c
374  *
375  * A base64 encoding algorithm
376  * For details, see http://sourceforge.net/projects/libb64
377  *
378  * Caller is responsible for freeing memory allocated to
379  * hold output buffer.
380  */
381 BU_EXPORT extern signed char *bu_b64_encode(const signed char *input);
382 
383 BU_EXPORT extern signed char *bu_b64_encode_block(const signed char* input, size_t length_in);
384 
385 BU_EXPORT extern int bu_b64_decode(signed char **output_buffer, const signed char *input);
386 
387 BU_EXPORT extern int bu_b64_decode_block(signed char **output_buffer, const signed char* input, size_t length_in);
388 
389 /** @} */
390 
391 /* TODO - make a "deprecated.h" file to stuff deprecated things in */
392 /** @addtogroup hton */
393 /** @{ */
394 
395 /** @file libbu/xdr.c
396  *
397  * DEPRECATED.
398  *
399  * Routines to implement an external data representation (XDR)
400  * compatible with the usual InterNet standards, e.g.:
401  * big-endian, twos-complement fixed point, and IEEE floating point.
402  *
403  * Routines to insert/extract short/long's into char arrays,
404  * independent of machine byte order and word-alignment.
405  * Uses encoding compatible with routines found in libpkg,
406  * and BSD system routines htonl(), htons(), ntohl(), ntohs().
407  *
408  */
409 
410 /**
411  * DEPRECATED: use ntohll()
412  * Macro version of library routine bu_glonglong()
413  * The argument is expected to be of type "unsigned char *"
414  */
415 #define BU_GLONGLONG(_cp) \
416  ((((uint64_t)((_cp)[0])) << 56) | \
417  (((uint64_t)((_cp)[1])) << 48) | \
418  (((uint64_t)((_cp)[2])) << 40) | \
419  (((uint64_t)((_cp)[3])) << 32) | \
420  (((uint64_t)((_cp)[4])) << 24) | \
421  (((uint64_t)((_cp)[5])) << 16) | \
422  (((uint64_t)((_cp)[6])) << 8) | \
423  ((uint64_t)((_cp)[7])))
424 /**
425  * DEPRECATED: use ntohl()
426  * Macro version of library routine bu_glong()
427  * The argument is expected to be of type "unsigned char *"
428  */
429 #define BU_GLONG(_cp) \
430  ((((uint32_t)((_cp)[0])) << 24) | \
431  (((uint32_t)((_cp)[1])) << 16) | \
432  (((uint32_t)((_cp)[2])) << 8) | \
433  ((uint32_t)((_cp)[3])))
434 /**
435  * DEPRECATED: use ntohs()
436  * Macro version of library routine bu_gshort()
437  * The argument is expected to be of type "unsigned char *"
438  */
439 #define BU_GSHORT(_cp) \
440  ((((uint16_t)((_cp)[0])) << 8) | \
441  (_cp)[1])
442 
443 /**
444  * DEPRECATED: use ntohs()
445  */
446 DEPRECATED BU_EXPORT extern uint16_t bu_gshort(const unsigned char *msgp);
447 
448 /**
449  * DEPRECATED: use ntohl()
450  */
451 DEPRECATED BU_EXPORT extern uint32_t bu_glong(const unsigned char *msgp);
452 
453 /**
454  * DEPRECATED: use htons()
455  */
456 DEPRECATED BU_EXPORT extern unsigned char *bu_pshort(unsigned char *msgp, uint16_t s);
457 
458 /**
459  * DEPRECATED: use htonl()
460  */
461 DEPRECATED BU_EXPORT extern unsigned char *bu_plong(unsigned char *msgp, uint32_t l);
462 
463 /**
464  * DEPRECATED: use htonll()
465  */
466 DEPRECATED BU_EXPORT extern unsigned char *bu_plonglong(unsigned char *msgp, uint64_t l);
467 
468 /** @} */
469 
471 
472 #endif /* BU_CV_H */
473 
474 /*
475  * Local Variables:
476  * mode: C
477  * tab-width: 8
478  * indent-tabs-mode: t
479  * c-file-style: "stroustrup"
480  * End:
481  * ex: shiftwidth=4 tabstop=8
482  */
DEPRECATED unsigned char * bu_plong(unsigned char *msgp, uint32_t l)
size_t bu_cv_itemlen(int cookie)
DEPRECATED unsigned char * bu_pshort(unsigned char *msgp, uint16_t s)
size_t bu_cv_ntohul(unsigned long int *, size_t, void *, size_t)
DEPRECATED unsigned char * bu_plonglong(unsigned char *msgp, uint64_t l)
DEPRECATED uint32_t bu_glong(const unsigned char *msgp)
Definition: xdr.c:63
if lu s
Definition: nmg_mod.c:3860
size_t bu_cv_ntohsl(signed long int *, size_t, void *, size_t)
int bu_b64_decode(signed char **output_buffer, const signed char *input)
Definition: b64.c:274
size_t bu_cv_htonul(void *, size_t, unsigned long *, size_t)
Header file for the BRL-CAD common definitions.
void bu_cv_htond(unsigned char *out, const unsigned char *in, size_t count)
int bu_b64_decode_block(signed char **output_buffer, const signed char *input, size_t length_in)
Definition: b64.c:247
size_t bu_cv_w_cookie(void *out, int outcookie, size_t size, void *in, int incookie, size_t count)
Definition: convert.c:474
size_t bu_cv_htonus(void *, size_t, unsigned short *, size_t)
size_t bu_cv(void *out, char *outfmt, size_t size, void *in, char *infmt, size_t count)
Definition: convert.c:250
#define DEPRECATED
Definition: common.h:303
size_t bu_cv_htonss(void *, size_t, signed short *, size_t)
#define __BEGIN_DECLS
Definition: common.h:73
DEPRECATED uint16_t bu_gshort(const unsigned char *msgp)
Definition: xdr.c:41
int bu_cv_cookie(const char *in)
Definition: convert.c:33
goto out
Definition: nmg_mod.c:3846
signed char * bu_b64_encode(const signed char *input)
Definition: b64.c:240
size_t bu_cv_ntohss(signed short *in, size_t count, void *out, size_t size)
Network TO Host Signed Short.
void bu_cv_ntohf(unsigned char *out, const unsigned char *in, size_t count)
void bu_cv_ntohd(unsigned char *out, const unsigned char *in, size_t count)
signed char * bu_b64_encode_block(const signed char *input, size_t length_in)
Definition: b64.c:212
void bu_cv_htonf(unsigned char *out, const unsigned char *in, size_t count)
size_t bu_cv_ntohus(unsigned short *, size_t, void *, size_t)
#define __END_DECLS
Definition: common.h:74
int bu_cv_optimize(int cookie)
size_t bu_cv_htonsl(void *, size_t, long *, size_t)