.. include:: ../global.rst

.. idio:currentmodule:: libc

libc structures
---------------

:lname:`Idio` supports the passing of opaque :lname:`C` pointers as
the ``C/pointer`` type.

Those ``C/pointer``\ s can be tagged with some type information which
can be used for access, setting (if appropriate) and printing.


.. _`libc/struct-group`:

struct group
^^^^^^^^^^^^^

:lname:`Idio` supports tagged references to :lname:`C` ``struct
group``:

.. code-block:: c

   struct group
   {
       char   *gr_name;
       char   *gr_passwd;
       gid_t   gr_gid;
       char  **gr_mem;
   };

See also :ref:`getgrgid <libc/getgrgid>` and :ref:`getgrnam
<libc/getgrnam>`.


.. _`libc/struct-group-ref`:

.. idio:function:: libc/struct-group-ref group member


   in C, :samp:`{group}->{member}`			
   					
   :param group: :ref:`struct-group <libc/struct-group>`	
   :type group: C/pointer		
   :param member: member name		
   :type member: symbol			
   :return: `group` -> `member`		
   :rtype:	varies on `member`		
   					
   Accessing `gr_mem` will return a list of strings.	


.. _`libc/struct-group-as-string`:

.. idio:function:: libc/struct-group-as-string group


   :param group: :ref:`struct-group <libc/struct-group>`	
   :type group: C/pointer			
   :return: string				
   :rtype:	string				


.. _`libc/struct-passwd`:

struct passwd
^^^^^^^^^^^^^

:lname:`Idio` supports tagged references to :lname:`C` ``struct
passwd``:

.. code-block:: c

   struct passwd
   {
       char   *pw_name;
       char   *pw_passwd;
       uid_t   pw_uid;
       gid_t   pw_gid;
       char   *pw_gecos;
       char   *pw_dir;
       char   *pw_shell;
   };

See also :ref:`getpwuid <libc/getpwuid>` and :ref:`getpwnam
<libc/getpwnam>`.


.. _`libc/struct-passwd-ref`:

.. idio:function:: libc/struct-passwd-ref passwd member


   in C, :samp:`{passwd}->{member}`			
   					
   :param passwd: :ref:`struct-passwd <libc/struct-passwd>`	
   :type passwd: C/pointer		
   :param member: member name		
   :type member: symbol			
   :return: `passwd` -> `member`		
   :rtype:	varies on `member`		


.. _`libc/struct-passwd-as-string`:

.. idio:function:: libc/struct-passwd-as-string passwd


   :param passwd: :ref:`struct-passwd <libc/struct-passwd>`	
   :type passwd: C/pointer			
   :return: string				
   :rtype:	string				


.. _`libc/struct-rlimit`:

struct rlimit
^^^^^^^^^^^^^

:lname:`Idio` supports tagged references to :lname:`C` ``struct
rlimit``:

.. code-block:: c

   struct rlimit
   {
     rlim_t               rlim_cur;
     rlim_t               rlim_max;
   };

using the structure member names ``rlim_cur`` and ``rlim_max``.

See also :ref:`getrlimit <libc/getrlimit>` and :ref:`setrlimit
<libc/setrlimit>`.


.. _`libc/struct-rlimit-ref`:

.. idio:function:: libc/struct-rlimit-ref rlimit member


   in C, :samp:`{rlimit}->{member}`	
   					
   :param rlimit: :ref:`struct-rlimit <libc/struct-rlimit>`	
   :type rlimit: C/pointer			
   :param member: member name		
   :type member: symbol			
   :return: `rlimit` -> `member`		
   :rtype:	varies on `member`		


.. _`libc/struct-rlimit-set!`:

.. idio:function:: libc/struct-rlimit-set! rlimit member val


   in C, :samp:`{rlimit}->{member} = {val}`	
   					
   :param rlimit: :ref:`struct-rlimit <libc/struct-rlimit>`	
   :type rlimit: C/pointer			
   :param member: member name		
   :type member: symbol			
   :param val: a C/ type			
   :type val: varies on `member`		
   :return: ``#<unspec>``			
   					
   The C/ types for `val` are `libc/rlim_t`.	


.. _`libc/struct-rlimit-as-string`:

.. idio:function:: libc/struct-rlimit-as-string rlimit


   :param rlimit: :ref:`struct-rlimit <libc/struct-rlimit>`	
   :type rlimit: C/pointer		
   :return: string			
   :rtype:	string			

   ``struct-rlimit-as-string`` is set to be the printer for a
   ``libc/struct-rlimit``.
   

.. _`libc/struct-rusage`:

struct rusage
^^^^^^^^^^^^^

:lname:`Idio` supports tagged references to :lname:`C` ``struct
rusage``:

.. code-block:: c

   struct rusage
   {
     struct timeval       ru_utime;
     struct timeval       ru_stime;
   };

using the structure member names ``ru_utime`` and ``ru_stime`` for
:ref:`struct-timeval <libc/struct-timeval>` structures.  The other
member names are not accessible due to portability concerns.

See also :ref:`getrusage <libc/getrusage>`.


.. _`libc/struct-rusage-ref`:

.. idio:function:: libc/struct-rusage-ref rusage member


   in C, :samp:`{rusage}->{member}`	
   					
   :param rusage: :ref:`struct-rusage <libc/struct-rusage>`	
   :type rusage: C/pointer			
   :param member: member name		
   :type member: symbol			
   :return: `rusage` -> `member`		
   :rtype:	varies on `member`		


.. _`libc/struct-rusage-as-string`:

.. idio:function:: libc/struct-rusage-as-string rusage


   :param rusage: :ref:`struct-rusage <libc/struct-rusage>`	
   :type rusage: C/pointer		
   :return: string			
   :rtype:	string			

   ``struct-rusage-as-string`` is set to be the printer for a
   ``libc/struct-rusage``.
   
   The code implicitly uses the underlying :lname:`C` code for
   :ref:`struct-timeval-as-string <libc/struct-timeval-as-string>`.
   

.. _`libc/struct-stat`:

struct stat
^^^^^^^^^^^

:lname:`Idio` supports tagged references to :lname:`C` ``struct
stat``:

.. code-block:: c

   struct stat
   {
     dev_t                st_dev;
     ino_t                st_ino;
     nlink_t              st_nlink;
     mode_t               st_mode;
     uid_t                st_uid;
     gid_t                st_gid;
     dev_t                st_rdev;
     off_t                st_size;
     blksize_t            st_blksize;
     blkcnt_t             st_blocks;
     struct timespec      st_atim;
     struct timespec      st_mtim;
     struct timespec      st_ctim;
   };

using the structure member names ``st_dev``, ``st_ino`` etc..

In addition the pseudo-member names ``st_atime``, ``st_mtime`` and
``st_ctime`` will access the ``tv_sec`` member of the corresponding
:ref:`struct-timespec <libc/struct-timespec>` members to maintain the
legacy interface.

See also :ref:`stat <libc/stat>` and :ref:`fstat <libc/fstat>`.


.. _`libc/struct-stat-as-string`:

.. idio:function:: libc/struct-stat-as-string stat


   :param stat: :ref:`struct-stat <libc/struct-stat>`	
   :type stat: C/pointer		
   :return: string			
   :rtype:	string			

   ``struct-stat-as-string`` is set to be the printer for a
   ``libc/struct-stat``.
   
   The code implicitly uses the underlying :lname:`C` code for
   :ref:`struct-timeval-as-string <libc/struct-timeval-as-string>`.
   

.. _`libc/struct-stat-ref`:

.. idio:function:: libc/struct-stat-ref stat member


   in C, :samp:`{stat}->{member}`		
   					
   :param stat: :ref:`struct-stat <libc/struct-stat>`	
   :type stat: C/pointer			
   :param member: member name		
   :type member: symbol			
   :return: `stat` -> `member`		
   :rtype:	varies on `member`		


.. _`libc/struct-statvfs`:

struct statvfs
^^^^^^^^^^^^^^

:lname:`Idio` supports tagged references to :lname:`C` ``struct
statvfs``:

.. code-block:: c

   struct statvfs
   {
       unsigned long  f_bsize;
       unsigned long  f_frsize;
       fsblkcnt_t     f_blocks;
       fsblkcnt_t     f_bfree;
       fsblkcnt_t     f_bavail;
       fsfilcnt_t     f_files;
       fsfilcnt_t     f_ffree;
       fsfilcnt_t     f_favail;
       unsigned long  f_fsid;
       unsigned long  f_flag;
       unsigned long  f_namemax;
   };

using the structure member names ``f_bsize``, ``f_frsize`` etc..

See also :ref:`statvfs <libc/statvfs>` and :ref:`fstatvfs
<libc/fstatvfs>`.

.. _`libc/struct-statvfs-as-string`:

.. idio:function:: libc/struct-statvfs-as-string statvfs


   :param statvfs: :ref:`struct-statvfs <libc/struct-statvfs>`	
   :type statvfs: C/pointer			
   :return: string				
   :rtype:	string				

   ``struct-statvfs-as-string`` is set to be the printer for a
   ``libc/struct-statvfs``.
   

.. _`libc/struct-statvfs-ref`:

.. idio:function:: libc/struct-statvfs-ref statvfs member


   in C, :samp:`{statvfs}->{member}`			
   					
   :param statvfs: :ref:`struct-statvfs <libc/struct-statvfs>`	
   :type statvfs: C/pointer		
   :param member: member name		
   :type member: symbol			
   :return: `statvfs` -> `member`		
   :rtype:	varies on `member`		


.. _`libc/struct-termios`:

struct termios
^^^^^^^^^^^^^^

:lname:`Idio` supports tagged references to :lname:`C` ``struct
termios``:

.. code-block:: c

   struct termios
   {
     tcflag_t             c_iflag;
     tcflag_t             c_oflag;
     tcflag_t             c_cflag;
     tcflag_t             c_lflag;
     cc_t[]               c_cc;
     speed_t              c_ispeed;
     speed_t              c_ospeed;
   };

using the structure member names ``c_iflag``, ``c_oflag`` etc..

Note that SunOS does not define either of ``c_ispeed`` or ``c_ospeed``
and OpenBSD defines ``speed_t`` as an ``int``.

Linux's ``c_line`` is not supported.

See also :ref:`tcgetattr <libc/tcgetattr>` and :ref:`tcsetattr
<libc/tcsetattr>`.


.. _`libc/struct-termios-ref`:

.. idio:function:: libc/struct-termios-ref termios member


   in C, :samp:`{termios}->{member}`	
   					
   :param termios: :ref:`struct-termios <libc/struct-termios>`	
   :type termios: C/pointer		
   :param member: member name		
   :type member: symbol			
   :return: `termios` -> `member`		
   :rtype:	varies on `member`		


.. _`libc/struct-termios-set!`:

.. idio:function:: libc/struct-termios-set! termios member val


   in C, :samp:`{termios}->{member} = {val}`	
   					
   :param termios: :ref:`struct-termios <libc/struct-termios>`	
   :type termios: C/pointer		
   :param member: member name		
   :type member: symbol			
   :param val: a C/ type			
   :type val: varies on `member`		
   :return: ``#<unspec>``			
   					
   The C/ types for `val` are `libc/tcflag_t`, `libc/speed_t` and `C/pointer` for `c_cc`.	


.. _`libc/struct-termios-as-string`:

.. idio:function:: libc/struct-termios-as-string termios


   :param termios: :ref:`struct-termios <libc/struct-termios>`	
   :type termios: C/pointer		
   :return: string				
   :rtype:	string				

   ``struct-termios-as-string`` is set to be the printer for a
   ``libc/struct-termios``.
   
   The ``c_cc`` member is not printed.
   

.. _`libc/struct-timespec`:

struct timespec
^^^^^^^^^^^^^^^

:lname:`Idio` supports tagged references to :lname:`C` ``struct
timespec``:

.. code-block:: c

   struct timespec
   {
     time_t               tv_sec;
     long		  tv_nsec;
   };

using the structure member names ``tv_sec`` and ``tv_nsec``.

Note that ``tv_nsec`` is defined as a ``long`` due to portability
issues.



.. _`libc/struct-timespec-ref`:

.. idio:function:: libc/struct-timespec-ref timespec member


   in C, :samp:`{timespec}->{member}`	
   					
   :param timespec: :ref:`struct-timespec <libc/struct-timespec>`	
   :type timespec: C/pointer		
   :param member: member name		
   :type member: symbol			
   :return: `timespec` -> `member`		
   :rtype:	varies on `member`		


.. _`libc/struct-timespec-set!`:

.. idio:function:: libc/struct-timespec-set! timespec member val


   in C, :samp:`{timespec}->{member} = {val}`	
   					
   :param timespec: :ref:`struct-timespec <libc/struct-timespec>`	
   :type timespec: C/pointer		
   :param member: member name		
   :type member: symbol			
   :param val: a C/ type			
   :type val: varies on `member`		
   :return: ``#<unspec>``			
   					
   The C/ types for `val` are `libc/time_t`, `C/long`.	


.. _`libc/struct-timespec-as-string`:

.. idio:function:: libc/struct-timespec-as-string timespec


   :param timespec: :ref:`struct-timespec <libc/struct-timespec>`	
   :type timespec: C/pointer		
   :return: string				
   :rtype:	string				

   ``struct-timespec-as-string`` is set to be the printer for a
   ``libc/struct-timespec``.
   
   The code prints the structure in a pseudo-floating point format:
   :samp:`{tv_sec}.{tv_nsec}` with the :samp:`{tv_nsec}` part formatted
   to 9 digits with leading 0 (zero) padding.
   

.. _`libc/struct-timeval`:

struct timeval
^^^^^^^^^^^^^^

:lname:`Idio` supports tagged references to :lname:`C` ``struct
timeval``:

.. code-block:: c

   struct timeval
   {
     time_t             tv_sec;
     suseconds_t        tv_usec;
   };

using the structure member names ``tv_sec`` and ``tv_usec``.

Note that on some systems ``suseconds_t`` may be typedef'd to a
``long``.

See also :ref:`gettimeofday <libc/gettimeofday>`.


.. _`libc/struct-timeval-ref`:

.. idio:function:: libc/struct-timeval-ref timeval member


   in C, :samp:`{timeval}->{member}`	
   					
   :param timeval: :ref:`struct-timeval <libc/struct-timeval>`	
   :type timeval: C/pointer		
   :param member: member name		
   :type member: symbol			
   :return: `timeval` -> `member`		
   :rtype:	varies on `member`		


.. _`libc/struct-timeval-set!`:

.. idio:function:: libc/struct-timeval-set! timeval member val


   in C, :samp:`{timeval}->{member} = {val}`	
   					
   :param timeval: :ref:`struct-timeval <libc/struct-timeval>`	
   :type timeval: C/pointer		
   :param member: member name		
   :type member: symbol			
   :param val: a C/ type			
   :type val: varies on `member`		
   :return: ``#<unspec>``			
   					
   The C/ types for `val` are `libc/time_t` or `libc/suseconds_t` (or `C/long` on OpenBSD).	


.. _`libc/subtract-struct-timeval`:

.. idio:function:: libc/subtract-struct-timeval tv1 tv2


   A simple function to calculate the difference between two C	
   struct timevals							
   								
   tv1 - tv2							
   								
   :param tv1: :ref:`struct-timeval <libc/struct-timeval>`		
   :type tv1: C/pointer						
   :param tv2: :ref:`struct-timeval <libc/struct-timeval>`		
   :type tv2: C/pointer						
   :return: :ref:`struct-timeval <libc/struct-timeval>`		
   :rtype: C/pointer						
   :raises ^system-error:						


.. _`libc/add-struct-timeval`:

.. idio:function:: libc/add-struct-timeval tv1 tv2


   A simple function to calculate the sum of two C struct timevals 
   								
   tv1 + tv2							
   								
   :param tv1: :ref:`struct-timeval <libc/struct-timeval>`		
   :type tv1: C/pointer						
   :param tv2: :ref:`struct-timeval <libc/struct-timeval>`		
   :type tv2: C/pointer						
   :return: :ref:`struct-timeval <libc/struct-timeval>`		
   :rtype: C/pointer						
   :raises ^system-error:						


.. _`libc/struct-timeval-as-string`:

.. idio:function:: libc/struct-timeval-as-string timeval


   :param timeval: :ref:`struct-timeval <libc/struct-timeval>`	
   :type timeval: C/pointer		
   :return: string				
   :rtype:	string				

   ``struct-timeval-as-string`` is set to be the printer for a
   ``libc/struct-timeval``.
   
   The code prints the structure in a pseudo-floating point format:
   :samp:`{tv_sec}.{tv_usec}` with the :samp:`{tv_usec}` part formatted
   to 6 digits with leading 0 (zero) padding.
   

.. _`libc/struct-tm`:

struct tm
^^^^^^^^^

:lname:`Idio` supports tagged references to :lname:`C` ``struct
tm``:

.. code-block:: c

   struct tm
   {
     int                  tm_sec;
     int                  tm_min;
     int                  tm_hour;
     int                  tm_mday;
     int                  tm_mon;
     int                  tm_year;
     int                  tm_wday;
     int                  tm_yday;
     int                  tm_isdst;
     long int             tm_gmtoff;
     char*                tm_zone;
   };

using the structure member names ``tm_sec``, ``tm_min`` etc..

Note that SunOS does not define ``tm_gmtoff`` or ``tm_zone``.

See also :ref:`asctime <libc/asctime>`, :ref:`localtime
<libc/localtime>`, :ref:`gmtime <libc/gmtime>`, :ref:`mktime
<libc/mktime>`, :ref:`strftime <libc/strftime>`, :ref:`strptime
<libc/strptime>`.


.. _`libc/struct-tm-ref`:

.. idio:function:: libc/struct-tm-ref tm member


   in C, :samp:`{tm}->{member}`		
   					
   :param tm: :ref:`struct-tm <libc/struct-tm>`	
   :type tm: C/pointer			
   :param member: member name		
   :type member: symbol			
   :return: `tm` -> `member`		
   :rtype:	varies on `member`		


.. _`libc/struct-tm-set!`:

.. idio:function:: libc/struct-tm-set! tm member val


   in C, :samp:`{tm}->{member} = {val}`	
   					
   :param tm: :ref:`struct-tm <libc/struct-tm>`	
   :type tm: C/pointer			
   :param member: member name		
   :type member: symbol			
   :param val: a C/ type			
   :type val: varies on `member`		
   :return: ``#<unspec>``			
   					
   The C/ types for `val` are `C/int`, `C/long` and `C/pointer` for `tm_zone`.	


.. _`libc/struct-tm-as-string`:

.. idio:function:: libc/struct-tm-as-string tm


   :param tm: :ref:`struct-tm <libc/struct-tm>`	
   :type tm: C/pointer			
   :return: string				
   :rtype:	string				

   ``struct-tm-as-string`` is set to be the printer for a
   ``libc/struct-tm``.
   
   

.. _`libc/struct-tms`:

struct tms
^^^^^^^^^^

:lname:`Idio` supports tagged references to :lname:`C` ``struct
tms``:

.. code-block:: c

   struct tms
   {
     clock_t              tms_utime;
     clock_t              tms_stime;
     clock_t              tms_cutime;
     clock_t              tms_cstime;
   };

using the structure member names ``tms_utime``, ``tms_stime`` etc..

See also :ref:`times <libc/times>`.


.. _`libc/struct-tms-ref`:

.. idio:function:: libc/struct-tms-ref tms member


   in C, :samp:`{tms}->{member}`		
   					
   :param tms: :ref:`struct-tms <libc/struct-tms>`	
   :type tms: C/pointer			
   :param member: member name		
   :type member: symbol			
   :return: `tms` -> `member`		
   :rtype:	varies on `member`		


.. _`libc/struct-tms-as-string`:

.. idio:function:: libc/struct-tms-as-string tms


   :param tms: :ref:`struct-tms <libc/struct-tms>`	
   :type tms: C/pointer		
   :return: string			
   :rtype:	string			

   ``struct-tms-as-string`` is set to be the printer for a
   ``libc/struct-tms``.
   
   

.. _`libc/struct-utsname`:

struct utsname
^^^^^^^^^^^^^^

:lname:`Idio` supports tagged references to :lname:`C` ``struct
utsname``:

.. code-block:: c

   struct utsname
   {
     char[]               sysname;
     char[]               nodename;
     char[]               release;
     char[]               version;
     char[]               machine;
     char[]               domainname;
   };

using the structure member names ``sysname``, ``nodename`` etc..

Note that ``domainname`` is only available on Linux.

See also :ref:`uname <libc/uname>` and :ref:`idio-uname
<libc/idio-uname>`.


.. _`libc/struct-utsname-ref`:

.. idio:function:: libc/struct-utsname-ref utsname member


   in C, :samp:`{utsname}->{member}`	
   					
   :param utsname: :ref:`struct-utsname <libc/struct-utsname>`	
   :type utsname: C/pointer		
   :param member: member name		
   :type member: symbol			
   :return: `utsname` -> `member`		
   :rtype:	varies on `member`		


.. _`libc/struct-utsname-as-string`:

.. idio:function:: libc/struct-utsname-as-string utsname


   :param utsname: :ref:`struct-utsname <libc/struct-utsname>`	
   :type utsname: C/pointer		
   :return: string				
   :rtype:	string				

   ``struct-utsname-as-string`` is set to be the printer for a
   ``libc/struct-utsname``.
   
   



.. include:: ../commit.rst