This is documentation for Mathematica 6, which was
based on an earlier version of the Wolfram Language.
View current documentation (Version 11.2)
MathLink C Function

MLGetByteString()

int MLGetByteString(MLINK link, const unsigned char **s, int *n, long spec)
gets a string of characters from the MathLink connection specified by link, storing the codes for the characters in s and the number of characters in n. The code spec is used for any character whose Mathematica character code is larger than 255.
  • MLGetByteString() allocates memory for the array of character codes. You must call MLReleaseByteString() to disown this memory. If MLGetByteString() fails and the function's return value indicates an error, do not call MLReleaseByteString() on the value contained in s.
  • MLGetByteString() is convenient in situations where no special characters occur.
  • The character codes used by MLGetByteString() are exactly the ones returned by ToCharacterCode in Mathematica.
  • The array of character codes in MLGetByteString() is not terminated by a null character.
  • Characters such as newlines are specified by their raw character codes, not by ASCII forms such as \n.
  • MLGetByteString() returns immutable data.
  • MLGetByteString() returns 0 in the event of an error, and a nonzero value if the function succeeds.
  • Use MLError() to retrieve the error code if MLGetByteString() fails.
  • MLGetByteString() is declared in the MathLink header file mathlink.h.
#include "mathlink.h"

/* read a string encoded with codes from ToCharacterCode[] from a link */

void f(MLINK lp)
{
    const unsigned char *string;
    int length;

    if(! MLGetByteString(lp, &string, &length, 0))
        {
            /* unable to read the byte string from lp */
            return;
        }

    /* ... */

    MLReleaseByteString(lp, string, length);
}