Update headers to cause warnings on unused returns and null args.

In places where an ignored return or a null-arg is a sure indication
of a bug add the GCC warning attributes. The null arg annotation
is not enable for Opus itself because it will cause the compiler
to optimize out some null checks. I don't trust our callers
quite that much.

4 files changed, 79 insertions, 56 deletions

diff --git a/include/opus.h b/include/opus.h
index fa1d913f..f89d0ec7 100644
--- a/include/opus.h
+++ b/include/opus.h
@@ -157,7 +157,7 @@ extern "C" {
   */
 typedef struct OpusEncoder OpusEncoder;
 
-OPUS_EXPORT int opus_encoder_get_size(int channels);
+OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_encoder_get_size(int channels);
 
 /**
  */
@@ -192,7 +192,7 @@ OPUS_EXPORT int opus_encoder_get_size(int channels);
  * selected is too low. This also means that it is safe to always use 48 kHz stereo input
  * and let the encoder optimize the encoding.
  */
-OPUS_EXPORT OpusEncoder *opus_encoder_create(
+OPUS_EXPORT OPUS_WARN_UNUSED_RESULT OpusEncoder *opus_encoder_create(
     opus_int32 Fs,
     int channels,
     int application,
@@ -215,7 +215,7 @@ OPUS_EXPORT int opus_encoder_init(
     opus_int32 Fs,
     int channels,
     int application
-);
+) OPUS_ARG_NONNULL(1);
 
 /** Encodes an Opus frame.
   * The passed frame_size must an opus frame size for the encoder's sampling rate.
@@ -229,13 +229,13 @@ OPUS_EXPORT int opus_encoder_init(
   * @param [in] max_data_bytes <tt>opus_int32</tt>: Allocated memory for payload; don't use for controlling bitrate
   * @returns length of the data payload (in bytes) or @ref opus_errorcodes
   */
-OPUS_EXPORT opus_int32 opus_encode(
+OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_encode(
     OpusEncoder *st,
     const opus_int16 *pcm,
     int frame_size,
     unsigned char *data,
     opus_int32 max_data_bytes
-);
+) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2) OPUS_ARG_NONNULL(4);
 
 /** Encodes an Opus frame from floating point input.
   * The passed frame_size must an opus frame size for the encoder's sampling rate.
@@ -249,13 +249,13 @@ OPUS_EXPORT opus_int32 opus_encode(
   * @param [in] max_data_bytes <tt>opus_int32</tt>: Allocated memory for payload; don't use for controlling bitrate
   * @returns length of the data payload (in bytes) or @ref opus_errorcodes
   */
-OPUS_EXPORT opus_int32 opus_encode_float(
+OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_encode_float(
     OpusEncoder *st,
     const float *pcm,
     int frame_size,
     unsigned char *data,
     opus_int32 max_data_bytes
-);
+) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2) OPUS_ARG_NONNULL(4);
 
 /** Frees an OpusEncoder allocated by opus_encoder_create.
   * @param[in] st <tt>OpusEncoder*</tt>: State to be freed.
@@ -268,7 +268,7 @@ OPUS_EXPORT void opus_encoder_destroy(OpusEncoder *st);
   * by a convenience macro.
   * @see opus_encoderctls
   */
-OPUS_EXPORT int opus_encoder_ctl(OpusEncoder *st, int request, ...);
+OPUS_EXPORT int opus_encoder_ctl(OpusEncoder *st, int request, ...) OPUS_ARG_NONNULL(1);
 /**@}*/
 
 /** @defgroup opus_decoder Opus Decoder
@@ -332,7 +332,7 @@ typedef struct OpusDecoder OpusDecoder;
   * @param [in] channels <tt>int</tt>: Number of channels
   * @returns size
   */
-OPUS_EXPORT int opus_decoder_get_size(int channels);
+OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_decoder_get_size(int channels);
 
 /** Allocates and initializes a decoder state.
   * @param [in] Fs <tt>opus_int32</tt>: Sample rate to decode at (Hz)
@@ -347,7 +347,7 @@ OPUS_EXPORT int opus_decoder_get_size(int channels);
   * rate. Likewise, the decoder is capable of filling in either mono or
   * interleaved stereo pcm buffers, at the caller's request.
   */
-OPUS_EXPORT OpusDecoder *opus_decoder_create(
+OPUS_EXPORT OPUS_WARN_UNUSED_RESULT OpusDecoder *opus_decoder_create(
     opus_int32 Fs,
     int channels,
     int *error
@@ -366,7 +366,7 @@ OPUS_EXPORT int opus_decoder_init(
     OpusDecoder *st,
     opus_int32 Fs,
     int channels
-);
+) OPUS_ARG_NONNULL(1);
 
 /** Decode an Opus frame
   * @param [in] st <tt>OpusDecoder*</tt>: Decoder state
@@ -380,14 +380,14 @@ OPUS_EXPORT int opus_decoder_init(
   *  decoded. If no such data is available the frame is decoded as if it were lost.
   * @returns Number of decoded samples or @ref opus_errorcodes
   */
-OPUS_EXPORT int opus_decode(
+OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_decode(
     OpusDecoder *st,
     const unsigned char *data,
     opus_int32 len,
     opus_int16 *pcm,
     int frame_size,
     int decode_fec
-);
+) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4);
 
 /** Decode an opus frame with floating point output
   * @param [in] st <tt>OpusDecoder*</tt>: Decoder state
@@ -401,14 +401,14 @@ OPUS_EXPORT int opus_decode(
   *  decoded. If no such data is available the frame is decoded as if it were lost.
   * @returns Number of decoded samples or @ref opus_errorcodes
   */
-OPUS_EXPORT int opus_decode_float(
+OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_decode_float(
     OpusDecoder *st,
     const unsigned char *data,
     opus_int32 len,
     float *pcm,
     int frame_size,
     int decode_fec
-);
+) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4);
 
 /** Perform a CTL function on an Opus decoder.
   *
@@ -416,7 +416,7 @@ OPUS_EXPORT int opus_decode_float(
   * by a convenience macro.
   * @see opus_genericctls
   */
-OPUS_EXPORT int opus_decoder_ctl(OpusDecoder *st, int request, ...);
+OPUS_EXPORT int opus_decoder_ctl(OpusDecoder *st, int request, ...) OPUS_ARG_NONNULL(1);
 
 /** Frees an OpusDecoder allocated by opus_decoder_create.
   * @param[in] st <tt>OpusDecoder*</tt>: State to be freed.
@@ -443,7 +443,7 @@ OPUS_EXPORT int opus_packet_parse(
    const unsigned char *frames[48],
    short size[48],
    int *payload_offset
-);
+) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4);
 
 /** Gets the bandwidth of an Opus packet.
   * @param [in] data <tt>char*</tt>: Opus packet
@@ -454,7 +454,7 @@ OPUS_EXPORT int opus_packet_parse(
   * @retval OPUS_BANDWIDTH_FULLBAND Fullband (20kHz bandpass)
   * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type
   */
-OPUS_EXPORT int opus_packet_get_bandwidth(const unsigned char *data);
+OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_packet_get_bandwidth(const unsigned char *data) OPUS_ARG_NONNULL(1);
 
 /** Gets the number of samples per frame from an Opus packet.
   * @param [in] data <tt>char*</tt>: Opus packet
@@ -462,14 +462,14 @@ OPUS_EXPORT int opus_packet_get_bandwidth(const unsigned char *data);
   * @returns Number of samples per frame
   * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type
   */
-OPUS_EXPORT int opus_packet_get_samples_per_frame(const unsigned char *data, opus_int32 Fs);
+OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_packet_get_samples_per_frame(const unsigned char *data, opus_int32 Fs) OPUS_ARG_NONNULL(1);
 
 /** Gets the number of channels from an Opus packet.
   * @param [in] data <tt>char*</tt>: Opus packet
   * @returns Number of channels
   * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type
   */
-OPUS_EXPORT int opus_packet_get_nb_channels(const unsigned char *data);
+OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_packet_get_nb_channels(const unsigned char *data) OPUS_ARG_NONNULL(1);
 
 /** Gets the number of frames in an Opus packet.
   * @param [in] packet <tt>char*</tt>: Opus packet
@@ -477,7 +477,7 @@ OPUS_EXPORT int opus_packet_get_nb_channels(const unsigned char *data);
   * @returns Number of frames
   * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type
   */
-OPUS_EXPORT int opus_packet_get_nb_frames(const unsigned char packet[], opus_int32 len);
+OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_packet_get_nb_frames(const unsigned char packet[], opus_int32 len) OPUS_ARG_NONNULL(1);
 
 /** Gets the number of samples of an Opus packet.
   * @param [in] dec <tt>OpusDecoder*</tt>: Decoder state
@@ -486,7 +486,7 @@ OPUS_EXPORT int opus_packet_get_nb_frames(const unsigned char packet[], opus_int
   * @returns Number of samples
   * @retval OPUS_INVALID_PACKET The compressed data passed is corrupted or of an unsupported type
   */
-OPUS_EXPORT int opus_decoder_get_nb_samples(const OpusDecoder *dec, const unsigned char packet[], opus_int32 len);
+OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_decoder_get_nb_samples(const OpusDecoder *dec, const unsigned char packet[], opus_int32 len) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2);
 /**@}*/
 
 /** @defgroup opus_repacketizer Repacketizer
@@ -499,21 +499,21 @@ OPUS_EXPORT int opus_decoder_get_nb_samples(const OpusDecoder *dec, const unsign
 
 typedef struct OpusRepacketizer OpusRepacketizer;
 
-OPUS_EXPORT int opus_repacketizer_get_size(void);
+OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_repacketizer_get_size(void);
 
-OPUS_EXPORT OpusRepacketizer *opus_repacketizer_init(OpusRepacketizer *rp);
+OPUS_EXPORT OpusRepacketizer *opus_repacketizer_init(OpusRepacketizer *rp) OPUS_ARG_NONNULL(1);
 
-OPUS_EXPORT OpusRepacketizer *opus_repacketizer_create(void);
+OPUS_EXPORT OPUS_WARN_UNUSED_RESULT OpusRepacketizer *opus_repacketizer_create(void);
 
 OPUS_EXPORT void opus_repacketizer_destroy(OpusRepacketizer *rp);
 
-OPUS_EXPORT int opus_repacketizer_cat(OpusRepacketizer *rp, const unsigned char *data, opus_int32 len);
+OPUS_EXPORT int opus_repacketizer_cat(OpusRepacketizer *rp, const unsigned char *data, opus_int32 len) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2);
 
-OPUS_EXPORT opus_int32 opus_repacketizer_out_range(OpusRepacketizer *rp, int begin, int end, unsigned char *data, opus_int32 maxlen);
+OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_repacketizer_out_range(OpusRepacketizer *rp, int begin, int end, unsigned char *data, opus_int32 maxlen) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4);
 
-OPUS_EXPORT int opus_repacketizer_get_nb_frames(OpusRepacketizer *rp);
+OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_repacketizer_get_nb_frames(OpusRepacketizer *rp) OPUS_ARG_NONNULL(1);
 
-OPUS_EXPORT opus_int32 opus_repacketizer_out(OpusRepacketizer *rp, unsigned char *data, opus_int32 maxlen);
+OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_repacketizer_out(OpusRepacketizer *rp, unsigned char *data, opus_int32 maxlen) OPUS_ARG_NONNULL(1);
 
 /**@}*/
 
diff --git a/include/opus_custom.h b/include/opus_custom.h
index 201b1b7e..e78f8d4c 100644
--- a/include/opus_custom.h
+++ b/include/opus_custom.h
@@ -81,7 +81,7 @@ typedef struct OpusCustomMode OpusCustomMode;
  @param error Returned error code (if NULL, no error will be returned)
  @return A newly created mode
 */
-OPUS_CUSTOM_EXPORT OpusCustomMode *opus_custom_mode_create(opus_int32 Fs, int frame_size, int *error);
+OPUS_CUSTOM_EXPORT OPUS_WARN_UNUSED_RESULT OpusCustomMode *opus_custom_mode_create(opus_int32 Fs, int frame_size, int *error);
 
 /** Destroys a mode struct. Only call this after all encoders and
     decoders using this mode are destroyed as well.
@@ -91,7 +91,7 @@ OPUS_CUSTOM_EXPORT void opus_custom_mode_destroy(OpusCustomMode *mode);
 
 /* Encoder */
 
-OPUS_CUSTOM_EXPORT_STATIC int opus_custom_encoder_get_size(const OpusCustomMode *mode, int channels);
+OPUS_CUSTOM_EXPORT_STATIC OPUS_WARN_UNUSED_RESULT int opus_custom_encoder_get_size(const OpusCustomMode *mode, int channels);
 
 /** Creates a new encoder state. Each stream needs its own encoder
     state (can't be shared across simultaneous streams).
@@ -102,7 +102,7 @@ OPUS_CUSTOM_EXPORT_STATIC int opus_custom_encoder_get_size(const OpusCustomMode
  @param error Returns an error code
  @return Newly created encoder state.
 */
-OPUS_CUSTOM_EXPORT OpusCustomEncoder *opus_custom_encoder_create(const OpusCustomMode *mode, int channels, int *error);
+OPUS_CUSTOM_EXPORT OPUS_WARN_UNUSED_RESULT OpusCustomEncoder *opus_custom_encoder_create(const OpusCustomMode *mode, int channels, int *error);
 
 OPUS_CUSTOM_EXPORT_STATIC int opus_custom_encoder_init(OpusCustomEncoder *st, const OpusCustomMode *mode, int channels);
 
@@ -129,7 +129,7 @@ OPUS_CUSTOM_EXPORT void opus_custom_encoder_destroy(OpusCustomEncoder *st);
  *       the length returned be somehow transmitted to the decoder. Otherwise, no
  *       decoding is possible.
 */
-OPUS_CUSTOM_EXPORT int opus_custom_encode_float(OpusCustomEncoder *st, const float *pcm, int frame_size, unsigned char *compressed, int maxCompressedBytes);
+OPUS_CUSTOM_EXPORT OPUS_WARN_UNUSED_RESULT int opus_custom_encode_float(OpusCustomEncoder *st, const float *pcm, int frame_size, unsigned char *compressed, int maxCompressedBytes);
 
 /** Encodes a frame of audio.
  @param st Encoder state
@@ -145,7 +145,7 @@ OPUS_CUSTOM_EXPORT int opus_custom_encode_float(OpusCustomEncoder *st, const flo
  *       the length returned be somehow transmitted to the decoder. Otherwise, no
  *       decoding is possible.
  */
-OPUS_CUSTOM_EXPORT int opus_custom_encode(OpusCustomEncoder *st, const opus_int16 *pcm, int frame_size, unsigned char *compressed, int maxCompressedBytes);
+OPUS_CUSTOM_EXPORT OPUS_WARN_UNUSED_RESULT int opus_custom_encode(OpusCustomEncoder *st, const opus_int16 *pcm, int frame_size, unsigned char *compressed, int maxCompressedBytes);
 
 /** Query and set encoder parameters
  @param st Encoder state
@@ -157,7 +157,7 @@ OPUS_CUSTOM_EXPORT int opus_custom_encoder_ctl(OpusCustomEncoder * restrict st,
 
 /* Decoder */
 
-OPUS_CUSTOM_EXPORT_STATIC int opus_custom_decoder_get_size(const OpusCustomMode *mode, int channels);
+OPUS_CUSTOM_EXPORT_STATIC OPUS_WARN_UNUSED_RESULT int opus_custom_decoder_get_size(const OpusCustomMode *mode, int channels);
 
 /** Creates a new decoder state. Each stream needs its own decoder state (can't
     be shared across simultaneous streams).
@@ -167,7 +167,7 @@ OPUS_CUSTOM_EXPORT_STATIC int opus_custom_decoder_get_size(const OpusCustomMode
  @param error Returns an error code
  @return Newly created decoder state.
  */
-OPUS_CUSTOM_EXPORT OpusCustomDecoder *opus_custom_decoder_create(const OpusCustomMode *mode, int channels, int *error);
+OPUS_CUSTOM_EXPORT OPUS_WARN_UNUSED_RESULT OpusCustomDecoder *opus_custom_decoder_create(const OpusCustomMode *mode, int channels, int *error);
 
 OPUS_CUSTOM_EXPORT_STATIC int opus_custom_decoder_init(OpusCustomDecoder *st, const OpusCustomMode *mode, int channels);
 
@@ -185,7 +185,7 @@ OPUS_CUSTOM_EXPORT void opus_custom_decoder_destroy(OpusCustomDecoder *st);
             returned here in float format.
  @return Error code.
    */
-OPUS_CUSTOM_EXPORT int opus_custom_decode_float(OpusCustomDecoder *st, const unsigned char *data, int len, float *pcm, int frame_size);
+OPUS_CUSTOM_EXPORT OPUS_WARN_UNUSED_RESULT int opus_custom_decode_float(OpusCustomDecoder *st, const unsigned char *data, int len, float *pcm, int frame_size);
 
 /** Decodes a frame of audio.
  @param st Decoder state
@@ -196,7 +196,7 @@ OPUS_CUSTOM_EXPORT int opus_custom_decode_float(OpusCustomDecoder *st, const uns
             returned here in 16-bit PCM format (native endian).
  @return Error code.
  */
-OPUS_CUSTOM_EXPORT int opus_custom_decode(OpusCustomDecoder *st, const unsigned char *data, int len, opus_int16 *pcm, int frame_size);
+OPUS_CUSTOM_EXPORT OPUS_WARN_UNUSED_RESULT int opus_custom_decode(OpusCustomDecoder *st, const unsigned char *data, int len, opus_int16 *pcm, int frame_size);
 
 /** Query and set decoder parameters
    @param st Decoder state
diff --git a/include/opus_defines.h b/include/opus_defines.h
index d984f997..54d198be 100644
--- a/include/opus_defines.h
+++ b/include/opus_defines.h
@@ -75,6 +75,29 @@ extern "C" {
 # define OPUS_EXPORT
 #endif
 
+# if !defined(OPUS_GNUC_PREREQ)
+#  if defined(__GNUC__)&&defined(__GNUC_MINOR__)
+#   define OPUS_GNUC_PREREQ(_maj,_min) \
+ ((__GNUC__<<16)+__GNUC_MINOR__>=((_maj)<<16)+(_min))
+#  else
+#   define OPUS_GNUC_PREREQ(_maj,_min) 0
+#  endif
+# endif
+
+/**Warning attributes for opus functions
+  * NONNULL is not used in OPUS_BUILD to avoid the compiler optimizing out
+  * some paranoid null checks. */
+#if defined(__GNUC__) && OPUS_GNUC_PREREQ(3, 4)
+# define OPUS_WARN_UNUSED_RESULT __attribute__ ((__warn_unused_result__))
+#else
+# define OPUS_WARN_UNUSED_RESULT
+#endif
+#if !defined(OPUS_BUILD) && defined(__GNUC__) && OPUS_GNUC_PREREQ(3, 4)
+# define OPUS_ARG_NONNULL(_x)  __attribute__ ((__nonnull__(_x)))
+#else
+# define OPUS_ARG_NONNULL(_x)
+#endif
+
 /** These are the actual Encoder CTL ID numbers.
   * They should not be used directly by applications. */
 #define OPUS_SET_APPLICATION_REQUEST         4000
diff --git a/include/opus_multistream.h b/include/opus_multistream.h
index e6562a7e..5e5364a3 100644
--- a/include/opus_multistream.h
+++ b/include/opus_multistream.h
@@ -54,7 +54,7 @@ typedef struct OpusMSDecoder OpusMSDecoder;
 /** Allocate and initialize a multistream encoder state object.
  *  Call opus_multistream_encoder_destroy() to release
  *  this object when finished. */
-OPUS_EXPORT OpusMSEncoder *opus_multistream_encoder_create(
+OPUS_EXPORT OPUS_WARN_UNUSED_RESULT OpusMSEncoder *opus_multistream_encoder_create(
       opus_int32 Fs,            /**< Sampling rate of input signal (Hz) */
       int channels,             /**< Number of channels in the input signal */
       int streams,              /**< Total number of streams to encode from the input */
@@ -62,7 +62,7 @@ OPUS_EXPORT OpusMSEncoder *opus_multistream_encoder_create(
       const unsigned char *mapping, /**< Encoded mapping between channels and streams */
       int application,          /**< Coding mode (OPUS_APPLICATION_VOIP/OPUS_APPLICATION_AUDIO) */
       int *error                /**< Error code */
-);
+) OPUS_ARG_NONNULL(5);
 
 /** Initialize an already allocated multistream encoder state. */
 OPUS_EXPORT int opus_multistream_encoder_init(
@@ -73,30 +73,30 @@ OPUS_EXPORT int opus_multistream_encoder_init(
       int coupled_streams,      /**< Number of coupled (stereo) streams to encode */
       const unsigned char *mapping, /**< Encoded mapping between channels and streams */
       int application           /**< Coding mode (OPUS_APPLICATION_VOIP/OPUS_APPLICATION_AUDIO) */
-);
+) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(6);
 
 /** Returns length of the data payload (in bytes) or a negative error code */
-OPUS_EXPORT int opus_multistream_encode(
+OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_multistream_encode(
     OpusMSEncoder *st,          /**< Encoder state */
     const opus_int16 *pcm,      /**< Input signal as interleaved samples. Length is frame_size*channels */
     int frame_size,             /**< Number of samples per frame of input signal */
     unsigned char *data,        /**< Output buffer for the compressed payload (no more than max_data_bytes long) */
     opus_int32 max_data_bytes   /**< Allocated memory for payload; don't use for controlling bitrate */
-);
+) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2) OPUS_ARG_NONNULL(4);
 
 /** Returns length of the data payload (in bytes) or a negative error code. */
-OPUS_EXPORT int opus_multistream_encode_float(
+OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_multistream_encode_float(
       OpusMSEncoder *st,        /**< Encoder state */
       const float *pcm,         /**< Input signal interleaved in channel order. length is frame_size*channels */
       int frame_size,           /**< Number of samples per frame of input signal */
       unsigned char *data,      /**< Output buffer for the compressed payload (no more than max_data_bytes long) */
       opus_int32 max_data_bytes /**< Allocated memory for payload; don't use for controlling bitrate */
-  );
+) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2) OPUS_ARG_NONNULL(4);
 
 /** Gets the size of an OpusMSEncoder structure.
   * @returns size
   */
-OPUS_EXPORT opus_int32 opus_multistream_encoder_get_size(
+OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_multistream_encoder_get_size(
       int streams,              /**< Total number of coded streams */
       int coupled_streams       /**< Number of coupled (stereo) streams */
 );
@@ -105,19 +105,19 @@ OPUS_EXPORT opus_int32 opus_multistream_encoder_get_size(
 OPUS_EXPORT void opus_multistream_encoder_destroy(OpusMSEncoder *st);
 
 /** Get or set options on a multistream encoder state */
-OPUS_EXPORT int opus_multistream_encoder_ctl(OpusMSEncoder *st, int request, ...);
+OPUS_EXPORT int opus_multistream_encoder_ctl(OpusMSEncoder *st, int request, ...) OPUS_ARG_NONNULL(1);
 
 /** Allocate and initialize a multistream decoder state object.
  *  Call opus_multistream_decoder_destroy() to release
  *  this object when finished. */
-OPUS_EXPORT OpusMSDecoder *opus_multistream_decoder_create(
+OPUS_EXPORT OPUS_WARN_UNUSED_RESULT OpusMSDecoder *opus_multistream_decoder_create(
       opus_int32 Fs,            /**< Sampling rate to decode at (Hz) */
       int channels,             /**< Number of channels to decode */
       int streams,              /**< Total number of coded streams in the multistream */
       int coupled_streams,      /**< Number of coupled (stereo) streams in the multistream */
       const unsigned char *mapping, /**< Stream to channel mapping table */
       int *error                /**< Error code */
-);
+) OPUS_ARG_NONNULL(5);
 
 /** Intialize a previously allocated decoder state object. */
 OPUS_EXPORT int opus_multistream_decoder_init(
@@ -127,10 +127,10 @@ OPUS_EXPORT int opus_multistream_decoder_init(
       int streams,              /**< Total number of coded streams */
       int coupled_streams,      /**< Number of coupled (stereo) streams */
       const unsigned char *mapping  /**< Stream to channel mapping table */
-);
+) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(6);
 
 /** Returns the number of samples decoded or a negative error code */
-OPUS_EXPORT int opus_multistream_decode(
+OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_multistream_decode(
     OpusMSDecoder *st,          /**< Decoder state */
     const unsigned char *data,  /**< Input payload. Use a NULL pointer to indicate packet loss */
     opus_int32 len,             /**< Number of bytes in payload */
@@ -138,10 +138,10 @@ OPUS_EXPORT int opus_multistream_decode(
     int frame_size,             /**< Number of samples per frame of input signal */
     int decode_fec              /**< Flag (0/1) to request that any in-band forward error correction data be */
                                 /**< decoded. If no such data is available the frame is decoded as if it were lost. */
-);
+) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4);
 
 /** Returns the number of samples decoded or a negative error code */
-OPUS_EXPORT int opus_multistream_decode_float(
+OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_multistream_decode_float(
     OpusMSDecoder *st,          /**< Decoder state */
     const unsigned char *data,  /**< Input payload buffer. Use a NULL pointer to indicate packet loss */
     opus_int32 len,             /**< Number of payload bytes in data */
@@ -149,18 +149,18 @@ OPUS_EXPORT int opus_multistream_decode_float(
     int frame_size,             /**< Number of samples per frame of input signal */
     int decode_fec              /**< Flag (0/1) to request that any in-band forward error correction data be */
                                 /**< decoded. If no such data is available the frame is decoded as if it were lost. */
-);
+) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4);
 
 /** Gets the size of an OpusMSDecoder structure.
   * @returns size
   */
-OPUS_EXPORT opus_int32 opus_multistream_decoder_get_size(
+OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_multistream_decoder_get_size(
       int streams,              /**< Total number of coded streams */
       int coupled_streams       /**< Number of coupled (stereo) streams */
 );
 
 /** Get or set options on a multistream decoder state */
-OPUS_EXPORT int opus_multistream_decoder_ctl(OpusMSDecoder *st, int request, ...);
+OPUS_EXPORT int opus_multistream_decoder_ctl(OpusMSDecoder *st, int request, ...) OPUS_ARG_NONNULL(1);
 
 /** Deallocate a multistream decoder state object */
 OPUS_EXPORT void opus_multistream_decoder_destroy(OpusMSDecoder *st);