# PXFSTRUCTCREATE

POSIX Subroutine: Creates an instance of the specified structure.

## Module

USE IFPOSIX

CALL PXFSTRUCTCREATE (structname,jhandle,ierror)

structname | (Input) Character. The name of the structure. As for any character string, the name must be specified in single or double quotes; for example, the structure `sigaction` would be specified as 'sigaction'. For more information on available structures, see the table below.
jhandle | (Output) INTEGER(4). The handle of the newly-created structure.
ierror | (Output) INTEGER(4). The error status.

If successful, ierror is set to zero; otherwise, an error code.

If your application passes information to the system, you should call one of the PXF(type)SET subroutines. If your application needs to get information from the structure, you should call one of the PXF(type)GET subroutines.

The following table shows:

- The structures that are available in the Fortran POSIX library

- The fields within each structure

- The subroutines you must use to access the structure fields

Structure Name | Field Names | Subroutines for Access
--- | --- | ---
sigset 1 | Fields are hidden. | PXFSIGEMPTYSET 1, PXFSIGFILLSET 1, PXFSIGADDSET 1, or PXFSIGDELSET 1
sigaction | sa_handler sa_mask sa_flags | PXFINTGET/PXFINTSET or PXFINT8GET/PXFINT8SET PXFINTGET/PXFINTSET or PXFINT8GET/PXFINT8SET PXFINTGET/PXFINTSET or PXFINT8GET/PXFINT8SET
utsname | sysname nodename release version machine | For all fields: PXFSTRGET
tms | tms_utime tms_stime tms_cutime tms_cstime | For all fields: PXFINTGET or PXFINT8GET
dirent | d_name | PXFSTRGET
stat | st_mode st_ino st_dev st_nlink st_uid st_gid st_size st_atime st_mtime st_ctime | For all fields: PXFINTGET or PXFINT8GET
utimbuf | actime modtime | For all fields: PXFINTGET or PXFINT8GET
flock 1 | l_type l_whence l_start l_len l_pid | For all fields: PXFINTGET or PXFINT8GET
termios 1 | c_iflag c_oflag c_cflag c_lflag c_cc | PXFINTGET/PXFINTSET or PXFINT8GET/PXFINT8SET PXFINTGET/PXFINTSET or PXFINT8GET/PXFINT8SET PXFINTGET/PXFINTSET or PXFINT8GET/PXFINT8SET PXFINTGET/PXFINTSET or PXFINT8GET/PXFINT8SET PXFAINTGET/PXFAINTSET or PXFAINT8GET/PXFAINT8SET
group 1 | gr_name gr_gid gr_nmem gr_mem | PXFSTRGET PXFINTGET or PXFINT8GET PXFINTGET or PXFINT8GET PXFESTRGET
passwd 1 | pw_name pw_uid pw_gid pw_dir pw_shell | PXFSTRGET PXFINTGET or PXFINT8GET PXFINTGET or PXFINT8GET PXFSTRGET PXFSTRGET
1L*X only

As for any character string, you must use single or double quotes when specifying a field name in a PXF(type)GET or PXF(type)SET subroutine. For example, field name sysname (in structure `utsname`) must be specified as 'sysname'.

## Example

    program test4
      use ifposix
      implicit none
      integer(jhandle_size) jhandle1,jhandle2
      integer(4) ierror,ilen1

      print *," Create a first instance for structure 'utsname' "
      call PXFSTRUCTCREATE("utsname",jhandle1,ierror)
      if(ierror.NE.0) STOP 'Error: cannot create structure for jhandle1'

      print *," Create a second instance for structure 'utsname' "
      call PXFSTRUCTCREATE("utsname",jhandle2,ierror)
      if(ierror.NE.0) then
         call PXFSTRUCTFREE(jhandle1,ierror)
         STOP 'test failed - cannot create structure for jhandle2'
      end if

      print *,"Fill the structure associated with jhandle1 with arbitrary data"
      call PXFSTRSET(jhandle1,"sysname","00000000000000",14,ierror)
      if(ierror.NE.0) call Error('Error: can't set component sysname for jhandle1')

      call PXFSTRSET(jhandle1,"Nodename","11111111111111",14,ierror)
      if(ierror.NE.0) call Error('Error: can't set component nodename for jhandle1')

      call PXFSTRSET(jhandle1,"RELEASE","22222222222222",14,ierror)
      if(ierror.NE.0) call Error('Error: can't set component release for jhandle1')

      call PXFSTRSET(jhandle1,"verSION","33333333333333",14,ierror)
      if(ierror.NE.0) call Error('Error: can't set component version for jhandle1')

      call PXFSTRSET(jhandle1,"machine","44444444444444",14,ierror)
      if(ierror.NE.0) call Error('Error: can't set component machine for jhandle1')

      print *,"Fill the structure associated with jhandle2 with arbitary data"
      call PXFSTRSET(jhandle2,"sysname","aaaaaaaaa",7,ierror)
      if(ierror.NE.0) call Error('Error: can't set component sysname for jhandle2')

      call PXFSTRSET(jhandle2,"Nodename","BBBBBBBBB  BBB",14,ierror)
      if(ierror.NE.0) call Error('Error: can't set component nodename for jhandle2')

      call PXFSTRSET(jhandle2,"RELEASE","cCCC cc-cccnc",12,ierror)
      if(ierror.NE.0) call Error('Error: can't set component release for jhandle2')

      call PXFSTRSET(jhandle2,"verSION","ddddd",1,ierror)
      if(ierror.NE.0) call Error('Error: can't set component version for jhandle2')

      call PXFSTRSET(jhandle2,"machine","eeeeeee",6,ierror)
      if(ierror.NE.0) call Error('Error: can't set component machine for jhandle2')

      print *,"Print contents of the structure associated with jhandle1"
      call PRINT_UTSNAME(jhandle1)

      print *,"Print contents of the structure associated with jhandle2"
      call PRINT_UTSNAME(jhandle2)

      print *,"Get operating system info into structure associated with jhandle1"
      call PXFUNAME(jhandle1,ierror)
      if(ierror.NE.0) call Error('Error: call to PXFUNAME has failed')

      print *,"Print contents of the structure associated with jhandle1"
      print*,"  returned from PXFUNAME"
      call PRINT_UTSNAME(jhandle1)

      print *,"Copy the contents of the structure associated with jhandle1"
      print *,"  into the structure associated with jhandle2"
      call PXFSTRUCTCOPY("utsname",jhandle1,jhandle2,ierror)
      if(ierror.NE.0) call Error('Error: can't copy jhandle1 contents into jhandle2')

      print *,"Print the contents of the structure associated with jhandle2."
      print *,"  It should be the same after copying."
      call PRINT_UTSNAME(jhandle2)

      print *,"Free memory for instance of structure associated with jhandle1"
      call PXFSTRUCTFREE(jhandle1,ierror)
      if(ierror.NE.0) STOP 'Error: can't free instance of structure for jhandle1'

      print *,"Free memory for instance of structure associated with jhandle2"
      call PXFSTRUCTFREE(jhandle2,ierror)
      if(ierror.NE.0) STOP 'Error: can't free instance of structure for jhandle2'

      print *,"Program terminated normally"
      call PXFEXIT(0)
    end

Parent topic: POSIX* Library Routines

## See Also

PXFSTRUCTFREE
the example in PXFTIMES