From c04dc355de4d706912bd5bdec887c7ceb2d99888 Mon Sep 17 00:00:00 2001 From: Jeff Squyres Date: Tue, 8 Sep 2020 07:43:54 -0700 Subject: [PATCH] mpi/man: convert MPI_Status conversion man pages to Markdown Convert the MPI_Status_f082f, MPI_Status_f082c, and MPI_Status_f2c man pages to Markdown. Fix some typos and improve the text a bit along the way. Left the raw NROFF redirect pages MPI_Status_f2f08, MPI_Status_c2f08, and MPI_Status_c2f files as they were -- they're 1-line redirects, and it seems simpler to leave those (vs. duplicating the Markdown). Signed-off-by: Jeff Squyres --- ompi/mpi/man/man3/MPI_Status_f082c.3.md | 58 ++++++++++++++++ ompi/mpi/man/man3/MPI_Status_f082c.3in | 30 -------- ompi/mpi/man/man3/MPI_Status_f082f.3.md | 92 +++++++++++++++++++++++++ ompi/mpi/man/man3/MPI_Status_f082f.3in | 56 --------------- ompi/mpi/man/man3/MPI_Status_f2c.3.md | 57 +++++++++++++++ ompi/mpi/man/man3/MPI_Status_f2c.3in | 30 -------- ompi/mpi/man/man3/Makefile.am | 8 +-- 7 files changed, 211 insertions(+), 120 deletions(-) create mode 100644 ompi/mpi/man/man3/MPI_Status_f082c.3.md delete mode 100644 ompi/mpi/man/man3/MPI_Status_f082c.3in create mode 100644 ompi/mpi/man/man3/MPI_Status_f082f.3.md delete mode 100644 ompi/mpi/man/man3/MPI_Status_f082f.3in create mode 100644 ompi/mpi/man/man3/MPI_Status_f2c.3.md delete mode 100644 ompi/mpi/man/man3/MPI_Status_f2c.3in diff --git a/ompi/mpi/man/man3/MPI_Status_f082c.3.md b/ompi/mpi/man/man3/MPI_Status_f082c.3.md new file mode 100644 index 0000000000..c9004565f7 --- /dev/null +++ b/ompi/mpi/man/man3/MPI_Status_f082c.3.md @@ -0,0 +1,58 @@ +# NAME + +MPI_Status_f082c, MPI_Status_c2f08 - Translates a C status into a Fortran 2008 status, or vice versa. + +# SYNTAX + +## C Syntax + +```c +#include + +int MPI_Status_f082c(const MPI_F08_status *f08_status, MPI_Status *c_status) +int MPI_Status_c2f08(const MPI_Status *c_status, MPI_F08_status *f08_status) +``` + +# PARAMETERS + +* `f08_status`: `mpi_f08`-style MPI status object +* `c_status`: C-style MPI status object + +# DESCRIPTION + +These two procedures are provided in C to convert from a Fortran 2008 +status (which is a derived type made of integers) to a C status (which +is a structure), and vice versa. The conversion occurs on all the +information in `status`, including that which is hidden. That is, +no status information is lost in the conversion. + +When using `MPI_Status_f082c()`, if `f08_status` is a valid Fortran +status, but not the Fortran value of `MPI_F08_STATUS_IGNORE` or +`MPI_F08_STATUSES_IGNORE`, then `MPI_Status_f082c()` returns in +`c_status` a valid C status with the same content. If `f08_status` is +the Fortran value of `MPI_STATUS_IGNORE` or `MPI_STATUSES_IGNORE`, or +if `f08_status` is not a valid Fortran status, then the call is +erroneous. + +When using `MPI_Status_c2f08()`, the opposite conversion is applied. If +`c_status` is `MPI_STATUS_IGNORE` or `MPI_STATUSES_IGNORE`, or if +`c_status` is not a valid C status, then the call is erroneous. + +The input status has the same source, tag and error code values as the +output status, and returns the same answers when queried for count, +elements, and cancellation. The conversion function may be called with +an input status argument that has an undefined error field, in which +case the value of the error field in the output status argument is +undefined. + +# NOTES + +These functions are only available in C; they are not available in any +of the Fortran MPI interfaces. + +# SEE ALSO + +[`MPI_Status_c2f`(3)](MPI_Status_c2f.html), +[`MPI_Status_f2c`(3)](MPI_Status_f2c.html), +[`MPI_Status_f082f`(3)](MPI_Status_f082f.html), +[`MPI_Status_f2f08`(3)](MPI_Status_f2f08.html) diff --git a/ompi/mpi/man/man3/MPI_Status_f082c.3in b/ompi/mpi/man/man3/MPI_Status_f082c.3in deleted file mode 100644 index e33b5e38ad..0000000000 --- a/ompi/mpi/man/man3/MPI_Status_f082c.3in +++ /dev/null @@ -1,30 +0,0 @@ -.\" -*- nroff -*- -.\" Copyright 2013 Los Alamos National Security, LLC. All rights reserved. -.\" Copyright 2006-2008 Sun Microsystems, Inc. -.\" Copyright (c) 1996 Thinking Machines Corporation -.\" Copyright (c) 2020 Research Organization for Information Science -.\" and Technology (RIST). All rights reserved. -.\" $COPYRIGHT$ -.TH MPI_Status_f082c 3 "#OMPI_DATE#" "#PACKAGE_VERSION#" "#PACKAGE_NAME#" -.SH NAME -\fBMPI_Status_f082c, MPI_Status_c2f08 \fP \- Translates a C status into a Fortran 2008 status, or vice versa. - -.SH SYNTAX -.ft R -.SH C Syntax -.nf -#include -int MPI_Status_f082c(const MPI_F08_status \fI*f08_status\fP, MPI_Status \fI*c_status\fP) -int MPI_Status_c2f08(const MPI_Status \fI*c_status\fP, MPI_F08_status \fI*f08_status\fP) - -.fi -.SH DESCRIPTION -.ft R -These two procedures are provided in C to convert from a Fortran 2008 status (which is a derived type made of integers) to a C status (which is a structure), and vice versa. The conversion occurs on all the information in \fIstatus\fP, including that which is hidden. That is, no status information is lost in the conversion. -.sp -When using MPI_Status_f082c, if \fIf08_status\fP is a valid Fortran status, but not the Fortran value of MPI_F08_STATUS_IGNORE or MPI_F08_STATUSES_IGNORE, then MPI_Status_f082c returns in \fIc_status\fP a valid C status with the same content. If \fIf08_status\fP is the Fortran value of MPI_STATUS_IGNORE or MPI_STATUSES_IGNORE, or if \fIf08_status\fP is not a valid Fortran status, then the call is erroneous. -.sp -When using MPI_Status_c2f08, the opposite conversion is applied. If \fIc_status\fP is MPI_STATUS_IGNORE or MPI_STATUSES_IGNORE, or if \fIc_status\fP is not a valid C status, then the call is erroneous. -.sp -The C status has the same source, tag and error code values as the Fortran status, and returns the same answers when queried for count, elements, and cancellation. The conversion function may be called with a Fortran status argument that has an undefined error field, in which case the value of the error field in the C status argument is undefined. -.sp diff --git a/ompi/mpi/man/man3/MPI_Status_f082f.3.md b/ompi/mpi/man/man3/MPI_Status_f082f.3.md new file mode 100644 index 0000000000..a53af76bef --- /dev/null +++ b/ompi/mpi/man/man3/MPI_Status_f082f.3.md @@ -0,0 +1,92 @@ +# NAME + +MPI_Status_f082f, MPI_Status_c2f08 - Translates a Fortran 2008 status into a Fortran INTEGER-style status, or vice versa. + +# SYNTAX + +## C Syntax + +```c +#include + +int MPI_Status_f082f(const MPI_F08_status *f08_status, MPI_Fint *f_status) +int MPI_Status_f2f08(const MPI_Fint *f_status, MPI_F08_status *f08_status) +``` + +## Fortran mpi Module Syntax + +```fortran +USE MPI + +MPI_STATUS_F082F(F08_STATUS, F_STATUS, IERROR) + TYPE(MPI_Status) :: F08_STATUS + INTEGER :: STATUS(MPI_STATUS_SIZE), IERROR + +MPI_STATUS_F2F08(F_STATUS, F08_STATUS, IERROR) + INTEGER :: F_STATUS(MPI_STATUS_SIZE), IERROR + TYPE(MPI_Status) :: F08_STATUS +``` + +## Fortran mpi_f08 Module Syntax + +```fortran +USE mpi_f08 + +MPI_Status_f082f(f08_status, f_status, ierror) + TYPE(MPI_Status), INTENT(IN) :: f08_status + INTEGER, INTENT(OUT) :: f_status(MPI_STATUS_SIZE) + INTEGER, OPTIONAL, INTENT(OUT) :: ierror + +MPI_Status_f2f08(f_status, f08_status, ierror) + INTEGER, INTENT(IN) :: f_status(MPI_STATUS_SIZE) + TYPE(MPI_Status), INTENT(OUT) :: f08_status + INTEGER, OPTIONAL, INTENT(OUT) :: ierror +``` + +# PARAMETERS + +* `f08_status`: `mpi_f08`-style MPI status object +* `f_status`: `mpi`-style `INTEGER` MPI status object + +# DESCRIPTION + +These two procedures are provided to convert from a Fortran 2008 +status (which is a derived datatype made of integers) to a Fortran +status (which is an array of integers), and vice versa. The conversion +occurs on all the information in `status`, including that which is +hidden. That is, no status information is lost in the conversion. + +When using `MPI_Status_f082f()`, if `f08_status` is a valid Fortran +status, but not the Fortran value of `MPI_F08_STATUS_IGNORE` (in C), +`MPI_STATUS_IGNORE` (in Fortran) or `MPI_F08_STATUSES_IGNORE` (in C) +or `MPI_STATUSES_IGNORE` (in Fortran), then `MPI_Status_f082f()` +returns in `f_status` a valid array with the same content. If +`f08_status` is the C value of `MPI_F08_STATUS_IGNORE` or +`MPI_F08_STATUSES_IGNORE` or the Fortran value of `MPI_STATUS_IGNORE` +or `MPI_STATUSES_IGNORE`, or if `f08_status` is not a valid Fortran +status, then the call is erroneous. + +When using `MPI_Status_f2f08()`, the opposite conversion is +applied. If `f_status` is `MPI_STATUS_IGNORE` or +`MPI_STATUSES_IGNORE`, or if `f_status` is not a valid Fortran status, +then the call is erroneous. + +The input status has the same source, tag and error code values as the +output status, and returns the same answers when queried for count, +elements, and cancellation. The conversion function may be called with +an input status argument that has an undefined error field, in which +case the value of the error field in the output status argument is +undefined. + +# NOTES + +The Fortran subroutines for these MPI routines are only available in +the `mpi` and `mpi_f08` modules (including the type specification for +`TYPE(MPI_Status); they are (intentionally) not available in `mpif.h`. + +# SEE ALSO + +[`MPI_Status_c2f`(3)](MPI_Status_c2f.html), +[`MPI_Status_f2c`(3)](MPI_Status_c2f.html), +[`MPI_Status_f082c`(3)](MPI_Status_f082c.html), +[`MPI_Status_c2f08`(3)](MPI_Status_c2f08.html) diff --git a/ompi/mpi/man/man3/MPI_Status_f082f.3in b/ompi/mpi/man/man3/MPI_Status_f082f.3in deleted file mode 100644 index fe975dbaa0..0000000000 --- a/ompi/mpi/man/man3/MPI_Status_f082f.3in +++ /dev/null @@ -1,56 +0,0 @@ -.\" -*- nroff -*- -.\" Copyright 2013 Los Alamos National Security, LLC. All rights reserved. -.\" Copyright 2006-2008 Sun Microsystems, Inc. -.\" Copyright (c) 1996 Thinking Machines Corporation -.\" Copyright (c) 2020 Research Organization for Information Science -.\" and Technology (RIST). All rights reserved. -.\" $COPYRIGHT$ -.TH MPI_Status_f082f 3 "#OMPI_DATE#" "#PACKAGE_VERSION#" "#PACKAGE_NAME#" -.SH NAME -\fBMPI_Status_f082f, MPI_Status_f2f08 \fP \- Translates a Fortran status into a Fortran 2008 status, or vice versa. - -.SH SYNTAX -.ft R -.SH C Syntax -.nf -#include -int MPI_Status_f082c(const MPI_F08_status \fI*f08_status\fP, MPI_Status \fI*c_status\fP) -int MPI_Status_c2f08(const MPI_Status \fI*c_status\fP, MPI_F08_status \fI*f08_status\fP) - -.fi -.SH Fortran Syntax -.nf -USE MPI -MPI_STATUS_F082F(\fF08_STATUS, F_STATUS, IERROR) - TYPE(MPI_STATUS), INTENT(IN) :: \fIF08_STATUS\fP - INTEGER \fISTATUS_MPI_STATUS_SIZE), IERROR\fP - -MPI_STATUS_F2F08(\fF_STATUS, F08_STATUS, IERROR) - INTEGER \fISTATUS_MPI_STATUS_SIZE), IERROR\fP - TYPE(MPI_STATUS), INTENT(OUT) :: \fIF08_STATUS\fP - -.fi -.SH Fortran 2008 Syntax -.nf -USE mpi_f08 -MPI_Status_f082f(\fIf08_status\fP, \fIf_status\fP, \fIierror\fP) - TYPE(MPI_Status), INTENT(IN) :: \fIf08_status\fP - INTEGER \fISTATUS(MPI_STATUS_SIZE)\fP - INTEGER, OPTIONAL, INTENT(OUT) :: \fIierror\fP - -MPI_Status_f2f08(\fIf_status\fP, \fIf08_status\fP, \fIierror\fP) - INTEGER \fISTATUS(MPI_STATUS_SIZE)\fP - TYPE(MPI_Status), INTENT(OUT) :: \fIf08_status\fP - -.fi -.SH DESCRIPTION -.ft R -These two procedures are provided to convert from a Fortran 2008 status (which is a derived datatype made of integers) to a Fortran status (which is an array of integers), and vice versa. The conversion occurs on all the information in \fIstatus\fP, including that which is hidden. That is, no status information is lost in the conversion. -These subroutines are not provided with the old \fIinclude 'mpif.h'\fP Fortran bindings. -.sp -When using MPI_Status_f082f, if \fIf08_status\fP is a valid Fortran status, but not the Fortran value of MPI_F08_STATUS_IGNORE (in C), MPI_STATUS_IGNORE (in Fortran) or MPI_F08_STATUSES_IGNORE (in C) or MPI_STATUSES_IGNORE (in Fortran), then MPI_Status_f082f returns in \fIf_status\fP a valid array with the same content. If \fIf08_status\fP is the C value of MPI_F08_STATUS_IGNORE or MPI_F08_STATUSES_IGNORE or the Fortran value of MPI_STATUS_IGNORE or MPI_STATUSES_IGNORE, or if \fIf08_status\fP is not a valid Fortran status, then the call is erroneous. -.sp -When using MPI_Status_f2f08, the opposite conversion is applied. If \fIf_status\fP is MPI_STATUS_IGNORE or MPI_STATUSES_IGNORE, or if \fIf_status\fP is not a valid Fortran status, then the call is erroneo$us. -.sp -The Fortran status has the same source, tag and error code values as the Fortran 2008 status, and returns the same answers when queried for count, elements, and cancellation. The conversion function may be called with a Fortran status argument that has an undefined error field, in which case the value of the error field in the Fortran status argument is undefined. -.sp diff --git a/ompi/mpi/man/man3/MPI_Status_f2c.3.md b/ompi/mpi/man/man3/MPI_Status_f2c.3.md new file mode 100644 index 0000000000..4f24ffdc93 --- /dev/null +++ b/ompi/mpi/man/man3/MPI_Status_f2c.3.md @@ -0,0 +1,57 @@ +# NAME + +MPI_Status_f2c, MPI_Status_f2c - Translates a C status into a Fortran INTEGER-style status, or vice versa. + +# SYNTAX + +## C Syntax + +```c +#include + +int MPI_Status_f2c(const MPI_Fint *f_status, MPI_Status *c_status) +int MPI_Status_c2f(const MPI_Status *c_status, MPI_Fint *f_status) +``` + +# PARAMETERS + +* `f_status`: `mpi`-style `INTEGER` MPI status object +* `c_status`: C-style MPI status object + +# DESCRIPTION + +These two procedures are provided in C to convert from a Fortran +status (which is an array of integers) to a C status (which is a +structure), and vice versa. The conversion occurs on all the +information in `status`, including that which is hidden. That is, +no status information is lost in the conversion. + +When using `MPI_Status_f2c()`, if `f_status` is a valid Fortran +status, but not the Fortran value of `MPI_STATUS_IGNORE` or +`MPI_STATUSES_IGNORE`, then `MPI_Status_f2c()` returns in `c_status` a +valid C status with the same content. If `f_status` is the Fortran +value of `MPI_STATUS_IGNORE` or `MPI_STATUSES_IGNORE`, or if +`f_status` is not a valid Fortran status, then the call is erroneous. + +When using `MPI_Status_c2f()`, the opposite conversion is applied. If +`c_status` is `MPI_STATUS_IGNORE` or `MPI_STATUSES_IGNORE`, or if +`c_status` is not a valid C status, then the call is erroneous. + +The input status has the same source, tag and error code values as the +output status, and returns the same answers when queried for count, +elements, and cancellation. The conversion function may be called with +an input status argument that has an undefined error field, in which +case the value of the error field in the output status argument is +undefined. + +# NOTES + +These functions are only available in C; they are not available in any +of the Fortran MPI interfaces. + +# SEE ALSO + +[`MPI_Status_f082c`(3)](MPI_Status_f082c.html), +[`MPI_Status_c2f08`(3)](MPI_Status_c2f08.html), +[`MPI_Status_f082f`(3)](MPI_Status_f082f.html), +[`MPI_Status_f2f08`(3)](MPI_Status_f2f08.html) diff --git a/ompi/mpi/man/man3/MPI_Status_f2c.3in b/ompi/mpi/man/man3/MPI_Status_f2c.3in deleted file mode 100644 index c28748be54..0000000000 --- a/ompi/mpi/man/man3/MPI_Status_f2c.3in +++ /dev/null @@ -1,30 +0,0 @@ -.\" -*- nroff -*- -.\" Copyright 2013 Los Alamos National Security, LLC. All rights reserved. -.\" Copyright 2006-2008 Sun Microsystems, Inc. -.\" Copyright (c) 1996 Thinking Machines Corporation -.\" $COPYRIGHT$ -.TH MPI_Status_f2c 3 "#OMPI_DATE#" "#PACKAGE_VERSION#" "#PACKAGE_NAME#" -.SH NAME -\fBMPI_Status_f2c, MPI_Status_c2f \fP \- Translates a C status into a Fortran status, or vice versa. - -.SH SYNTAX -.ft R -.SH C Syntax -.nf -#include -int MPI_Status_f2c(const MPI_Fint \fI*f_status\fP, MPI_Status \fI*c_status\fP) -int MPI_Status_c2f(const MPI_Status \fI*c_status\fP, MPI_Fint \fI*f_status\fP) - -.fi -.SH DESCRIPTION -.ft R -These two procedures are provided in C to convert from a Fortran status (which is an array of integers) to a C status (which is a structure), and vice versa. The conversion occurs on all the information in \fIstatus\fP, including that which is hidden. That is, no status information is lost in the conversion. -.sp -When using MPI_Status_f2c, if \fIf_status\fP is a valid Fortran status, but not the Fortran value of MPI_STATUS_IGNORE or MPI_STATUSES_IGNORE, then MPI_Status_f2c returns in \fIc_status\fP a valid C status with the same content. If \fIf_status\fP is the Fortran value of MPI_STATUS_IGNORE or MPI_STATUSES_IGNORE, or if \fIf_status\fP is not a valid Fortran status, then the call is erroneous. -.sp -When using MPI_Status_c2f, the opposite conversion is applied. If \fIc_status\fP is MPI_STATUS_IGNORE or MPI_STATUSES_IGNORE, or if \fIc_status\fP is not a valid C status, then the call is erroneous. -.sp -The C status has the same source, tag and error code values as the Fortran status, and returns the same answers when queried for count, elements, and cancellation. The conversion function may be called with a Fortran status argument that has an undefined error field, in which case the value of the error field in the C status argument is undefined. -.sp - - diff --git a/ompi/mpi/man/man3/Makefile.am b/ompi/mpi/man/man3/Makefile.am index 0a4a655bc0..f44459f4fb 100644 --- a/ompi/mpi/man/man3/Makefile.am +++ b/ompi/mpi/man/man3/Makefile.am @@ -24,7 +24,10 @@ include $(top_srcdir)/Makefile.ompi-rules # https://rmarkdown.rstudio.com/authoring_pandoc_markdown.html MD_FILES = \ - MPI_T_init_thread.3.md + MPI_T_init_thread.3.md \ + MPI_Status_f2c.3.md \ + MPI_Status_f082c.3.md \ + MPI_Status_f082f.3.md TEMPLATE_FILES = \ MPI_Abort.3in \ @@ -315,9 +318,6 @@ TEMPLATE_FILES = \ MPI_Startall.3in \ MPI_Status_c2f08.3in \ MPI_Status_c2f.3in \ - MPI_Status_f082c.3in \ - MPI_Status_f082f.3in \ - MPI_Status_f2c.3in \ MPI_Status_f2f08.3in \ MPI_Status_set_cancelled.3in \ MPI_Status_set_elements.3in \