.\" NS Rv user macro
.\" NS   return values
.\" NS
.\" NS width register 'Rv' set in doc-common
.\" NS
.\" NS local variables:
.\" NS   doc-str-Rv-std-prefix
.\" NS   doc-str-Rv-std-suffix
.\" NS   doc-str-Rv-stds-prefix
.\" NS   doc-str-Rv-stds-and
.\" NS   doc-str-Rv-stds-suffix
.\" NS   doc-str-Rv-std0
.
.ds doc-str-Rv-std-prefix "The
.ds doc-str-Rv-std-suffix "function returns the value\~0 if successful;
.as doc-str-Rv-std-suffix " otherwise the value\~\-1 is returned and
.as doc-str-Rv-std-suffix " the global variable \*[doc-Va-font]errno\f[]
.as doc-str-Rv-std-suffix " is set to indicate the error.
.
.ds doc-str-Rv-stds-prefix "The
.ds doc-str-Rv-stds-and    "and
.ds doc-str-Rv-stds-suffix "functions return the value\~0 if successful;
.as doc-str-Rv-stds-suffix " otherwise the value\~\-1 is returned and
.as doc-str-Rv-stds-suffix " the global variable \*[doc-Va-font]errno\f[]
.as doc-str-Rv-stds-suffix " is set to indicate the error.
.
.ds doc-str-Rv-std0 "Upon successful completion, the value\~0 is returned;
.as doc-str-Rv-std0 " otherwise the value\~\-1 is returned and
.as doc-str-Rv-std0 " the global variable \*[doc-Va-font]errno\f[]
.as doc-str-Rv-std0 " is set to indicate the error.
.
.de Rv
.
.\" XXX: what does this function without '-std'?
.
.  if \n[doc-arg-limit] \{\
.    tm Usage: .Rv not callable by other macros (#\n[.c])
.    doc-reset-args
.    return
.  \}
.
.  if !\n[.$] \{\
.    tm Usage: .Rv [-std] [<function> ...] (#\n[.c])
.    return
.  \}
.
.  if "\$1"-std" \{\
.    nr doc-reg-Rv \*[doc-section]
.    if ((\n[doc-reg-Rv] < 2) : (\n[doc-reg-Rv] > 3)) \
.      tm Usage: .Rv -std in sections 2 and 3 only (#\n[.c])
.    br
.    shift
.    ie (\n[.$] > 1) \{\
.      nop \)\*[doc-str-Rv-stds-prefix]
.      nr doc-reg-Rv 1
.      while (\n[doc-reg-Rv] < \n[.$]) \{\
.        ie (\n[.$] > 2) \
.          Fn \$\n[doc-reg-Rv] ,
.        el \
.          Fn \$\n[doc-reg-Rv]
.        nr doc-reg-Rv +1
.      \}
.      nop \)\*[doc-str-Rv-stds-and]
.      Fn \$\n[.$]
.      nop \)\*[doc-str-Rv-stds-suffix]
.    \}
.    el \{ .ie (\n[.$] == 1) \{\
.      nop \)\*[doc-str-Rv-std-prefix]
.      Fn \$1
.      nop \)\*[doc-str-Rv-std-suffix]
.    \}
.    el \{\
.      nop \)\*[doc-str-Rv-std0]
.  \}\}\}
..