private.h File Reference

Usenet network mailbox type; talk to an NNTP server. More...

#include <stdbool.h>
#include <stdint.h>
#include "lib.h"

Include dependency graph for private.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	NNTP_PORT   119
#define	NNTP_SSL_PORT   563

Enumerations
enum	NntpStatus { NNTP_NONE = 0 , NNTP_OK , NNTP_BYE }
	NNTP server return values. More...

Functions
void	nntp_acache_free (struct NntpMboxData *mdata)
	Remove all temporarily cache files.
int	nntp_active_save_cache (struct NntpAccountData *adata)
	Save list of all newsgroups to cache.
int	nntp_add_group (char *line, void *data)
	Parse newsgroup.
void	nntp_article_status (struct Mailbox *m, struct Email *e, char *group, anum_t anum)
	Get status of articles from .newsrc.
void	nntp_bcache_update (struct NntpMboxData *mdata)
	Remove stale cached messages.
int	nntp_check_new_groups (struct Mailbox *m, struct NntpAccountData *adata)
	Check for new groups/articles in subscribed groups.
void	nntp_delete_group_cache (struct NntpMboxData *mdata)
	Remove hcache and bcache of newsgroup.
void	nntp_group_unread_stat (struct NntpMboxData *mdata)
	Count number of unread articles using .newsrc data.
void	nntp_hash_destructor_t (int type, void *obj, intptr_t data)
void	nntp_hashelem_free (int type, void *obj, intptr_t data)
	Free our hash table data - Implements hash_hdata_free_t -.
struct HeaderCache *	nntp_hcache_open (struct NntpMboxData *mdata)
	Open newsgroup hcache.
void	nntp_hcache_update (struct NntpMboxData *mdata, struct HeaderCache *hc)
	Remove stale cached headers.
void	nntp_newsrc_gen_entries (struct Mailbox *m)
	Generate array of .newsrc entries.
int	nntp_open_connection (struct NntpAccountData *adata)
	Connect to server, authenticate and get capabilities.

Detailed Description

Usenet network mailbox type; talk to an NNTP server.

Authors

• Richard Russon

Copyright

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

Definition in file private.h.

Macro Definition Documentation

NNTP_PORT

#define NNTP_PORT   119

Definition at line 36 of file private.h.

NNTP_SSL_PORT

#define NNTP_SSL_PORT   563

Definition at line 37 of file private.h.

Enumeration Type Documentation

NntpStatus

enum NntpStatus

NNTP server return values.

Enumerator
NNTP_NONE	No connection to server.
NNTP_OK	Connected to server.
NNTP_BYE	Disconnected from server.

Definition at line 42 of file private.h.

{
  NNTP_NONE = 0, 
  NNTP_OK,       
  NNTP_BYE,      
};

Function Documentation

nntp_acache_free()

void nntp_acache_free

(

struct NntpMboxData *

mdata

)

Remove all temporarily cache files.

Parameters

mdata

NNTP Mailbox data

Definition at line 106 of file newsrc.c.

{
  for (int i = 0; i < NNTP_ACACHE_LEN; i++)
  {
    if (mdata->acache[i].path)
    {
      unlink(mdata->acache[i].path);
      FREE(&mdata->acache[i].path);
    }
  }
}

Here is the caller graph for this function:

nntp_active_save_cache()

int nntp_active_save_cache

(

struct NntpAccountData *

adata

)

Save list of all newsgroups to cache.

Parameters

adata

NNTP server

Return values

0	Success
-1	Failure

Definition at line 649 of file newsrc.c.

{
  if (!adata->cacheable)
    return 0;
 
  size_t buflen = 10240;
  char *buf = mutt_mem_calloc(1, buflen);
  snprintf(buf, buflen, "%lu\n", (unsigned long) adata->newgroups_time);
  size_t off = strlen(buf);
 
  for (unsigned int i = 0; i < adata->groups_num; i++)
  {
    struct NntpMboxData *mdata = adata->groups_list[i];
 
    if (!mdata || mdata->deleted)
      continue;
 
    if ((off + strlen(mdata->group) + (mdata->desc ? strlen(mdata->desc) : 0) + 50) > buflen)
    {
      buflen *= 2;
      mutt_mem_realloc(&buf, buflen);
    }
    snprintf(buf + off, buflen - off, "%s " ANUM_FMT " " ANUM_FMT " %c%s%s\n",
             mdata->group, mdata->last_message, mdata->first_message,
             mdata->allowed ? 'y' : 'n', mdata->desc ? " " : "",
             mdata->desc ? mdata->desc : "");
    off += strlen(buf + off);
  }
 
  char file[PATH_MAX] = { 0 };
  cache_expand(file, sizeof(file), &adata->conn->account, ".active");
  mutt_debug(LL_DEBUG1, "Updating %s\n", file);
  int rc = update_file(file, buf);
  FREE(&buf);
  return rc;
}

Here is the call graph for this function:

Here is the caller graph for this function:

nntp_add_group()

int nntp_add_group	(	char *	line,
		void *	data
	)

Parse newsgroup.

Parameters

line	String to parse
data	NNTP data

Return values

0

Always

Definition at line 574 of file newsrc.c.

{
  struct NntpAccountData *adata = data;
  struct NntpMboxData *mdata = NULL;
  char group[1024] = { 0 };
  char desc[8192] = { 0 };
  char mod = '\0';
  anum_t first = 0, last = 0;
 
  if (!adata || !line)
    return 0;
 
  /* These sscanf limits must match the sizes of the group and desc arrays */
  if (sscanf(line, "%1023s " ANUM_FMT " " ANUM_FMT " %c %8191[^\n]", group,
             &last, &first, &mod, desc) < 4)
  {
    mutt_debug(LL_DEBUG2, "Can't parse server line: %s\n", line);
    return 0;
  }
 
  mdata = mdata_find(adata, group);
  mdata->deleted = false;
  mdata->first_message = first;
  mdata->last_message = last;
  mdata->allowed = (mod == 'y') || (mod == 'm');
  mutt_str_replace(&mdata->desc, desc);
  if (mdata->newsrc_ent || (mdata->last_cached != 0))
    nntp_group_unread_stat(mdata);
  else if (mdata->last_message && (mdata->first_message <= mdata->last_message))
    mdata->unread = mdata->last_message - mdata->first_message + 1;
  else
    mdata->unread = 0;
  return 0;
}

Here is the call graph for this function:

Here is the caller graph for this function:

nntp_article_status()

void nntp_article_status	(	struct Mailbox *	m,
		struct Email *	e,
		char *	group,
		anum_t	anum
	)

Get status of articles from .newsrc.

Parameters

m	Mailbox
e	Email
group	Newsgroup
anum	Article number

Full status flags are not supported by nntp, but we can fake some of them: Read = a read message number is in the .newsrc New = not read and not cached Old = not read but cached

Definition at line 1255 of file newsrc.c.

{
  struct NntpMboxData *mdata = m->mdata;
 
  if (group)
    mdata = mutt_hash_find(mdata->adata->groups_hash, group);
 
  if (!mdata)
    return;
 
  for (unsigned int i = 0; i < mdata->newsrc_len; i++)
  {
    if ((anum >= mdata->newsrc_ent[i].first) && (anum <= mdata->newsrc_ent[i].last))
    {
      /* can't use mutt_set_flag() because mview_update() didn't get called yet */
      e->read = true;
      return;
    }
  }
 
  /* article was not cached yet, it's new */
  if (anum > mdata->last_cached)
    return;
 
  /* article isn't read but cached, it's old */
  const bool c_mark_old = cs_subset_bool(NeoMutt->sub, "mark_old");
  if (c_mark_old)
    e->old = true;
}

Here is the call graph for this function:

Here is the caller graph for this function:

nntp_bcache_update()

void nntp_bcache_update

(

struct NntpMboxData *

mdata

)

Remove stale cached messages.

Parameters

mdata

NNTP Mailbox data

Definition at line 801 of file newsrc.c.

{
  mutt_bcache_list(mdata->bcache, nntp_bcache_delete, mdata);
}

Here is the call graph for this function:

Here is the caller graph for this function:

nntp_check_new_groups()

int nntp_check_new_groups	(	struct Mailbox *	m,
		struct NntpAccountData *	adata
	)

Check for new groups/articles in subscribed groups.

Parameters

m	Mailbox
adata	NNTP server

Return values

1	New groups found
0	No new groups
-1	Error

Definition at line 2105 of file nntp.c.

{
  struct NntpMboxData tmp_mdata = { 0 };
  time_t now = 0;
  char buf[1024] = { 0 };
  char *msg = _("Checking for new newsgroups...");
  unsigned int i;
  int rc, update_active = false;
 
  if (!adata || !adata->newgroups_time)
    return -1;
 
  /* check subscribed newsgroups for new articles */
  const bool c_show_new_news = cs_subset_bool(NeoMutt->sub, "show_new_news");
  if (c_show_new_news)
  {
    mutt_message(_("Checking for new messages..."));
    for (i = 0; i < adata->groups_num; i++)
    {
      struct NntpMboxData *mdata = adata->groups_list[i];
 
      if (mdata && mdata->subscribed)
      {
        rc = nntp_group_poll(mdata, true);
        if (rc < 0)
          return -1;
        if (rc > 0)
          update_active = true;
      }
    }
  }
  else if (adata->newgroups_time)
  {
    return 0;
  }
 
  /* get list of new groups */
  mutt_message("%s", msg);
  if (nntp_date(adata, &now) < 0)
    return -1;
  tmp_mdata.adata = adata;
  if (m && m->mdata)
    tmp_mdata.group = ((struct NntpMboxData *) m->mdata)->group;
  else
    tmp_mdata.group = NULL;
  i = adata->groups_num;
  struct tm tm = mutt_date_gmtime(adata->newgroups_time);
  snprintf(buf, sizeof(buf), "NEWGROUPS %02d%02d%02d %02d%02d%02d GMT\r\n",
           tm.tm_year % 100, tm.tm_mon + 1, tm.tm_mday, tm.tm_hour, tm.tm_min, tm.tm_sec);
  rc = nntp_fetch_lines(&tmp_mdata, buf, sizeof(buf), msg, nntp_add_group, adata);
  if (rc)
  {
    if (rc > 0)
    {
      mutt_error("NEWGROUPS: %s", buf);
    }
    return -1;
  }
 
  /* new groups found */
  rc = 0;
  if (adata->groups_num != i)
  {
    int groups_num = i;
 
    adata->newgroups_time = now;
    for (; i < adata->groups_num; i++)
    {
      struct NntpMboxData *mdata = adata->groups_list[i];
      mdata->has_new_mail = true;
    }
 
    /* loading descriptions */
    const bool c_nntp_load_description = cs_subset_bool(NeoMutt->sub, "nntp_load_description");
    if (c_nntp_load_description)
    {
      unsigned int count = 0;
      struct Progress *progress = progress_new(MUTT_PROGRESS_READ, adata->groups_num - i);
      progress_set_message(progress, _("Loading descriptions..."));
 
      for (i = groups_num; i < adata->groups_num; i++)
      {
        struct NntpMboxData *mdata = adata->groups_list[i];
 
        if (get_description(mdata, NULL, NULL) < 0)
        {
          progress_free(&progress);
          return -1;
        }
        progress_update(progress, ++count, -1);
      }
      progress_free(&progress);
    }
    update_active = true;
    rc = 1;
  }
  if (update_active)
    nntp_active_save_cache(adata);
  mutt_clear_error();
  return rc;
}

Here is the call graph for this function:

Here is the caller graph for this function:

nntp_delete_group_cache()

void nntp_delete_group_cache

(

struct NntpMboxData *

mdata

)

Remove hcache and bcache of newsgroup.

Parameters

mdata

NNTP Mailbox data

Definition at line 810 of file newsrc.c.

{
  if (!mdata || !mdata->adata || !mdata->adata->cacheable)
    return;
 
#ifdef USE_HCACHE
  struct Buffer *file = buf_pool_get();
  nntp_hcache_namer(mdata->group, file);
  cache_expand(file->data, file->dsize, &mdata->adata->conn->account, buf_string(file));
  unlink(buf_string(file));
  mdata->last_cached = 0;
  mutt_debug(LL_DEBUG2, "%s\n", buf_string(file));
  buf_pool_release(&file);
#endif
 
  if (!mdata->bcache)
  {
    mdata->bcache = mutt_bcache_open(&mdata->adata->conn->account, mdata->group);
  }
  if (mdata->bcache)
  {
    mutt_debug(LL_DEBUG2, "%s/*\n", mdata->group);
    mutt_bcache_list(mdata->bcache, nntp_bcache_delete, NULL);
    mutt_bcache_close(&mdata->bcache);
  }
}

Here is the call graph for this function:

Here is the caller graph for this function:

nntp_group_unread_stat()

void nntp_group_unread_stat

(

struct NntpMboxData *

mdata

)

Count number of unread articles using .newsrc data.

Parameters

mdata

NNTP Mailbox data

Definition at line 136 of file newsrc.c.

{
  mdata->unread = 0;
  if ((mdata->last_message == 0) ||
      (mdata->first_message > mdata->last_message) || !mdata->newsrc_ent)
  {
    return;
  }
 
  mdata->unread = mdata->last_message - mdata->first_message + 1;
  for (unsigned int i = 0; i < mdata->newsrc_len; i++)
  {
    anum_t first = mdata->newsrc_ent[i].first;
    if (first < mdata->first_message)
      first = mdata->first_message;
    anum_t last = mdata->newsrc_ent[i].last;
    if (last > mdata->last_message)
      last = mdata->last_message;
    if (first <= last)
      mdata->unread -= last - first + 1;
  }
}

Here is the caller graph for this function:

nntp_hash_destructor_t()

void nntp_hash_destructor_t	(	int	type,
		void *	obj,
		intptr_t	data
	)

nntp_hcache_open()

struct HeaderCache * nntp_hcache_open

(

struct NntpMboxData *

mdata

)

Open newsgroup hcache.

Parameters

mdata

NNTP Mailbox data

Return values

ptr	Header cache
NULL	Error

Definition at line 709 of file newsrc.c.

{
  struct Url url = { 0 };
  char file[PATH_MAX] = { 0 };
 
  const bool c_save_unsubscribed = cs_subset_bool(NeoMutt->sub, "save_unsubscribed");
  if (!mdata->adata || !mdata->adata->cacheable || !mdata->adata->conn || !mdata->group ||
      !(mdata->newsrc_ent || mdata->subscribed || c_save_unsubscribed))
  {
    return NULL;
  }
 
  mutt_account_tourl(&mdata->adata->conn->account, &url);
  url.path = mdata->group;
  url_tostring(&url, file, sizeof(file), U_PATH);
  const char *const c_news_cache_dir = cs_subset_path(NeoMutt->sub, "news_cache_dir");
  return hcache_open(c_news_cache_dir, file, nntp_hcache_namer, true);
}

Here is the call graph for this function:

Here is the caller graph for this function:

nntp_hcache_update()

void nntp_hcache_update	(	struct NntpMboxData *	mdata,
		struct HeaderCache *	hc
	)

Remove stale cached headers.

Parameters

mdata	NNTP Mailbox data
hc	Header cache

Definition at line 733 of file newsrc.c.

{
  if (!hc)
    return;
 
  char buf[32] = { 0 };
  bool old = false;
  anum_t first = 0, last = 0;
 
  /* fetch previous values of first and last */
  char *hdata = hcache_fetch_raw_str(hc, "index", 5);
  if (hdata)
  {
    mutt_debug(LL_DEBUG2, "hcache_fetch_email index: %s\n", hdata);
    if (sscanf(hdata, ANUM_FMT " " ANUM_FMT, &first, &last) == 2)
    {
      old = true;
      mdata->last_cached = last;
 
      /* clean removed headers from cache */
      for (anum_t current = first; current <= last; current++)
      {
        if ((current >= mdata->first_message) && (current <= mdata->last_message))
          continue;
 
        snprintf(buf, sizeof(buf), ANUM_FMT, current);
        mutt_debug(LL_DEBUG2, "hcache_delete_email %s\n", buf);
        hcache_delete_email(hc, buf, strlen(buf));
      }
    }
    FREE(&hdata);
  }
 
  /* store current values of first and last */
  if (!old || (mdata->first_message != first) || (mdata->last_message != last))
  {
    snprintf(buf, sizeof(buf), ANUM_FMT " " ANUM_FMT, mdata->first_message,
             mdata->last_message);
    mutt_debug(LL_DEBUG2, "hcache_store_email index: %s\n", buf);
    hcache_store_raw(hc, "index", 5, buf, strlen(buf) + 1);
  }
}

Here is the call graph for this function:

Here is the caller graph for this function:

nntp_newsrc_gen_entries()

void nntp_newsrc_gen_entries

(

struct Mailbox *

m

)

Generate array of .newsrc entries.

Parameters

m

Mailbox

Definition at line 303 of file newsrc.c.

{
  if (!m)
    return;
 
  struct NntpMboxData *mdata = m->mdata;
  anum_t last = 0, first = 1;
  bool series;
  unsigned int entries;
 
  const enum SortType c_sort = cs_subset_sort(NeoMutt->sub, "sort");
  if (c_sort != SORT_ORDER)
  {
    cs_subset_str_native_set(NeoMutt->sub, "sort", SORT_ORDER, NULL);
    mailbox_changed(m, NT_MAILBOX_RESORT);
  }
 
  entries = mdata->newsrc_len;
  if (!entries)
  {
    entries = 5;
    mdata->newsrc_ent = mutt_mem_calloc(entries, sizeof(struct NewsrcEntry));
  }
 
  /* Set up to fake initial sequence from 1 to the article before the
   * first article in our list */
  mdata->newsrc_len = 0;
  series = true;
  for (int i = 0; i < m->msg_count; i++)
  {
    struct Email *e = m->emails[i];
    if (!e)
      break;
 
    /* search for first unread */
    if (series)
    {
      /* We don't actually check sequential order, since we mark
       * "missing" entries as read/deleted */
      last = nntp_edata_get(e)->article_num;
      if ((last >= mdata->first_message) && !e->deleted && !e->read)
      {
        if (mdata->newsrc_len >= entries)
        {
          entries *= 2;
          mutt_mem_realloc(&mdata->newsrc_ent, entries * sizeof(struct NewsrcEntry));
        }
        mdata->newsrc_ent[mdata->newsrc_len].first = first;
        mdata->newsrc_ent[mdata->newsrc_len].last = last - 1;
        mdata->newsrc_len++;
        series = false;
      }
    }
    else
    {
      /* search for first read */
      if (e->deleted || e->read)
      {
        first = last + 1;
        series = true;
      }
      last = nntp_edata_get(e)->article_num;
    }
  }
 
  if (series && (first <= mdata->last_loaded))
  {
    if (mdata->newsrc_len >= entries)
    {
      entries++;
      mutt_mem_realloc(&mdata->newsrc_ent, entries * sizeof(struct NewsrcEntry));
    }
    mdata->newsrc_ent[mdata->newsrc_len].first = first;
    mdata->newsrc_ent[mdata->newsrc_len].last = mdata->last_loaded;
    mdata->newsrc_len++;
  }
  mutt_mem_realloc(&mdata->newsrc_ent, mdata->newsrc_len * sizeof(struct NewsrcEntry));
 
  if (c_sort != SORT_ORDER)
  {
    cs_subset_str_native_set(NeoMutt->sub, "sort", c_sort, NULL);
    mailbox_changed(m, NT_MAILBOX_RESORT);
  }
}

Here is the call graph for this function:

Here is the caller graph for this function:

nntp_open_connection()

int nntp_open_connection

(

struct NntpAccountData *

adata

)

Connect to server, authenticate and get capabilities.

Parameters

adata

NNTP server

Return values

0	Success
-1	Failure

Definition at line 1766 of file nntp.c.

{
  if (adata->status == NNTP_OK)
    return 0;
  if (adata->status == NNTP_BYE)
    return -1;
  adata->status = NNTP_NONE;
 
  struct Connection *conn = adata->conn;
  if (mutt_socket_open(conn) < 0)
    return -1;
 
  char buf[256] = { 0 };
  int cap;
  bool posting = false, auth = true;
  int rc = -1;
 
  if (mutt_socket_readln(buf, sizeof(buf), conn) < 0)
  {
    nntp_connect_error(adata);
    goto done;
  }
 
  if (mutt_str_startswith(buf, "200"))
  {
    posting = true;
  }
  else if (!mutt_str_startswith(buf, "201"))
  {
    mutt_socket_close(conn);
    mutt_str_remove_trailing_ws(buf);
    mutt_error("%s", buf);
    goto done;
  }
 
  /* get initial capabilities */
  cap = nntp_capabilities(adata);
  if (cap < 0)
    goto done;
 
  /* tell news server to switch to mode reader if it isn't so */
  if (cap > 0)
  {
    if ((mutt_socket_send(conn, "MODE READER\r\n") < 0) ||
        (mutt_socket_readln(buf, sizeof(buf), conn) < 0))
    {
      nntp_connect_error(adata);
      goto done;
    }
 
    if (mutt_str_startswith(buf, "200"))
    {
      posting = true;
    }
    else if (mutt_str_startswith(buf, "201"))
    {
      posting = false;
    }
    else if (adata->hasCAPABILITIES)
    {
      /* error if has capabilities, ignore result if no capabilities */
      mutt_socket_close(conn);
      mutt_error(_("Could not switch to reader mode"));
      goto done;
    }
 
    /* recheck capabilities after MODE READER */
    if (adata->hasCAPABILITIES)
    {
      cap = nntp_capabilities(adata);
      if (cap < 0)
        goto done;
    }
  }
 
  mutt_message(_("Connected to %s. %s"), conn->account.host,
               posting ? _("Posting is ok") : _("Posting is NOT ok"));
  mutt_sleep(1);
 
#ifdef USE_SSL
  /* Attempt STARTTLS if available and desired. */
  const bool c_ssl_force_tls = cs_subset_bool(NeoMutt->sub, "ssl_force_tls");
  if ((adata->use_tls != 1) && (adata->hasSTARTTLS || c_ssl_force_tls))
  {
    if (adata->use_tls == 0)
    {
      adata->use_tls = c_ssl_force_tls ||
                               (query_quadoption(_("Secure connection with TLS?"),
                                                 NeoMutt->sub, "ssl_starttls") == MUTT_YES) ?
                           2 :
                           1;
    }
    if (adata->use_tls == 2)
    {
      if ((mutt_socket_send(conn, "STARTTLS\r\n") < 0) ||
          (mutt_socket_readln(buf, sizeof(buf), conn) < 0))
      {
        nntp_connect_error(adata);
        goto done;
      }
      // Clear any data after the STARTTLS acknowledgement
      mutt_socket_empty(conn);
      if (!mutt_str_startswith(buf, "382"))
      {
        adata->use_tls = 0;
        mutt_error("STARTTLS: %s", buf);
      }
      else if (mutt_ssl_starttls(conn))
      {
        adata->use_tls = 0;
        adata->status = NNTP_NONE;
        mutt_socket_close(adata->conn);
        mutt_error(_("Could not negotiate TLS connection"));
        goto done;
      }
      else
      {
        /* recheck capabilities after STARTTLS */
        cap = nntp_capabilities(adata);
        if (cap < 0)
          goto done;
      }
    }
  }
#endif
 
  /* authentication required? */
  if (conn->account.flags & MUTT_ACCT_USER)
  {
    if (!conn->account.user[0])
      auth = false;
  }
  else
  {
    if ((mutt_socket_send(conn, "STAT\r\n") < 0) ||
        (mutt_socket_readln(buf, sizeof(buf), conn) < 0))
    {
      nntp_connect_error(adata);
      goto done;
    }
    if (!mutt_str_startswith(buf, "480"))
      auth = false;
  }
 
  /* authenticate */
  if (auth && (nntp_auth(adata) < 0))
    goto done;
 
  /* get final capabilities after authentication */
  if (adata->hasCAPABILITIES && (auth || (cap > 0)))
  {
    cap = nntp_capabilities(adata);
    if (cap < 0)
      goto done;
    if (cap > 0)
    {
      mutt_socket_close(conn);
      mutt_error(_("Could not switch to reader mode"));
      goto done;
    }
  }
 
  /* attempt features */
  if (nntp_attempt_features(adata) < 0)
    goto done;
 
  rc = 0;
  adata->status = NNTP_OK;
 
done:
  return rc;
}

Here is the call graph for this function:

Here is the caller graph for this function: