summaryrefslogtreecommitdiffstats
path: root/libc
diff options
context:
space:
mode:
Diffstat (limited to 'libc')
-rw-r--r--libc/dns/gethnamaddr.c4
-rw-r--r--libc/dns/include/resolv_cache.h11
-rw-r--r--libc/dns/include/resolv_netid.h5
-rw-r--r--libc/dns/include/resolv_private.h10
-rw-r--r--libc/dns/net/getaddrinfo.c4
-rw-r--r--libc/dns/resolv/res_cache.c128
-rw-r--r--libc/dns/resolv/res_send.c37
-rw-r--r--libc/kernel/uapi/linux/ion.h37
8 files changed, 140 insertions, 96 deletions
diff --git a/libc/dns/gethnamaddr.c b/libc/dns/gethnamaddr.c
index cc33c61..0bd838e 100644
--- a/libc/dns/gethnamaddr.c
+++ b/libc/dns/gethnamaddr.c
@@ -565,7 +565,7 @@ android_read_hostent(FILE* proxy)
char buf[4];
if (fread(buf, 1, sizeof(buf), proxy) != sizeof(buf)) return NULL;
- /* This is reading serialized data from system/netd/DnsProxyListener.cpp
+ /* This is reading serialized data from system/netd/server/DnsProxyListener.cpp
* and changes here need to be matched there */
int result_code = strtol(buf, NULL, 10);
if (result_code != DnsProxyQueryResult) {
@@ -763,7 +763,7 @@ gethostbyname_internal(const char *name, int af, res_state res, unsigned netid,
netid = __netdClientDispatch.netIdForResolv(netid);
- /* This is writing to system/netd/DnsProxyListener.cpp and changes
+ /* This is writing to system/netd/server/DnsProxyListener.cpp and changes
* here need to be matched there */
if (fprintf(proxy, "gethostbyname %u %s %d",
netid,
diff --git a/libc/dns/include/resolv_cache.h b/libc/dns/include/resolv_cache.h
index 16f3e43..e049d95 100644
--- a/libc/dns/include/resolv_cache.h
+++ b/libc/dns/include/resolv_cache.h
@@ -32,11 +32,6 @@
#include <sys/cdefs.h>
struct __res_state;
-struct resolv_cache; /* forward */
-
-/* Gets the cache for a network. Returned cache might be NULL. */
-__LIBC_HIDDEN__
-extern struct resolv_cache* __get_res_cache(unsigned netid);
/* sets the name server addresses to the provided res_state structure. The
* name servers are retrieved from the cache which is associated
@@ -53,7 +48,7 @@ typedef enum {
__LIBC_HIDDEN__
extern ResolvCacheStatus
-_resolv_cache_lookup( struct resolv_cache* cache,
+_resolv_cache_lookup( unsigned netid,
const void* query,
int querylen,
void* answer,
@@ -65,7 +60,7 @@ _resolv_cache_lookup( struct resolv_cache* cache,
*/
__LIBC_HIDDEN__
extern void
-_resolv_cache_add( struct resolv_cache* cache,
+_resolv_cache_add( unsigned netid,
const void* query,
int querylen,
const void* answer,
@@ -74,7 +69,7 @@ _resolv_cache_add( struct resolv_cache* cache,
/* Notify the cache a request failed */
__LIBC_HIDDEN__
extern void
-_resolv_cache_query_failed( struct resolv_cache* cache,
+_resolv_cache_query_failed( unsigned netid,
const void* query,
int querylen);
diff --git a/libc/dns/include/resolv_netid.h b/libc/dns/include/resolv_netid.h
index bada18a..e5521b8 100644
--- a/libc/dns/include/resolv_netid.h
+++ b/libc/dns/include/resolv_netid.h
@@ -36,7 +36,7 @@
#include <netinet/in.h>
/*
- * Passing NETID_UNSET as the netId causes system/netd/DnsProxyListener.cpp to
+ * Passing NETID_UNSET as the netId causes system/netd/server/DnsProxyListener.cpp to
* fill in the appropriate default netId for the query.
*/
#define NETID_UNSET 0u
@@ -72,6 +72,9 @@ struct hostent *android_gethostbyaddrfornet_proxy(const void *, socklen_t, int ,
int android_getnameinfofornet(const struct sockaddr *, socklen_t, char *, size_t, char *, size_t,
int, unsigned, unsigned);
+/* delete the cache associated with a certain network */
+extern void _resolv_delete_cache_for_net(unsigned netid);
+
__END_DECLS
#endif /* _RESOLV_NETID_H */
diff --git a/libc/dns/include/resolv_private.h b/libc/dns/include/resolv_private.h
index 5a1f25c..4a832d0 100644
--- a/libc/dns/include/resolv_private.h
+++ b/libc/dns/include/resolv_private.h
@@ -498,6 +498,16 @@ __LIBC_HIDDEN__ void res_setnetid(res_state, unsigned);
__LIBC_HIDDEN__ void res_setmark(res_state, unsigned);
u_int res_randomid(void);
+#ifdef __i386__
+# define __socketcall extern __attribute__((__cdecl__))
+#else
+# define __socketcall extern
+#endif
+
+__socketcall int __connect(int, const struct sockaddr*, socklen_t);
+
+#undef __socketcall
+
__END_DECLS
#pragma GCC visibility pop
diff --git a/libc/dns/net/getaddrinfo.c b/libc/dns/net/getaddrinfo.c
index a492318..5443999 100644
--- a/libc/dns/net/getaddrinfo.c
+++ b/libc/dns/net/getaddrinfo.c
@@ -369,7 +369,7 @@ _test_connect(int pf, struct sockaddr *addr, size_t addrlen, unsigned mark) {
return 0;
int ret;
do {
- ret = connect(s, addr, addrlen);
+ ret = __connect(s, addr, addrlen);
} while (ret < 0 && errno == EINTR);
int success = (ret == 0);
do {
@@ -1803,7 +1803,7 @@ _find_src_addr(const struct sockaddr *addr, struct sockaddr *src_addr, unsigned
if (mark != MARK_UNSET && setsockopt(sock, SOL_SOCKET, SO_MARK, &mark, sizeof(mark)) < 0)
return 0;
do {
- ret = connect(sock, addr, len);
+ ret = __connect(sock, addr, len);
} while (ret == -1 && errno == EINTR);
if (ret == -1) {
diff --git a/libc/dns/resolv/res_cache.c b/libc/dns/resolv/res_cache.c
index dd77693..15d04c2 100644
--- a/libc/dns/resolv/res_cache.c
+++ b/libc/dns/resolv/res_cache.c
@@ -1218,7 +1218,6 @@ typedef struct resolv_cache {
int max_entries;
int num_entries;
Entry mru_list;
- pthread_mutex_t lock;
int last_id;
Entry* entries;
PendingReqInfo pending_requests;
@@ -1236,6 +1235,15 @@ struct resolv_cache_info {
#define HTABLE_VALID(x) ((x) != NULL && (x) != HTABLE_DELETED)
+static pthread_once_t _res_cache_once = PTHREAD_ONCE_INIT;
+static void _res_cache_init(void);
+
+// lock protecting everything in the _resolve_cache_info structs (next ptr, etc)
+static pthread_mutex_t _res_cache_list_lock;
+
+/* gets cache associated with a network, or NULL if none exists */
+static struct resolv_cache* _find_named_cache_locked(unsigned netid);
+
static void
_cache_flush_pending_requests_locked( struct resolv_cache* cache )
{
@@ -1256,18 +1264,18 @@ _cache_flush_pending_requests_locked( struct resolv_cache* cache )
}
}
-/* return 0 if no pending request is found matching the key
- * if a matching request is found the calling thread will wait
- * and return 1 when released */
+/* Return 0 if no pending request is found matching the key.
+ * If a matching request is found the calling thread will wait until
+ * the matching request completes, then update *cache and return 1. */
static int
-_cache_check_pending_request_locked( struct resolv_cache* cache, Entry* key )
+_cache_check_pending_request_locked( struct resolv_cache** cache, Entry* key, unsigned netid )
{
struct pending_req_info *ri, *prev;
int exist = 0;
- if (cache && key) {
- ri = cache->pending_requests.next;
- prev = &cache->pending_requests;
+ if (*cache && key) {
+ ri = (*cache)->pending_requests.next;
+ prev = &(*cache)->pending_requests;
while (ri) {
if (ri->hash == key->hash) {
exist = 1;
@@ -1288,7 +1296,9 @@ _cache_check_pending_request_locked( struct resolv_cache* cache, Entry* key )
struct timespec ts = {0,0};
XLOG("Waiting for previous request");
ts.tv_sec = _time_now() + PENDING_REQUEST_TIMEOUT;
- pthread_cond_timedwait(&ri->cond, &cache->lock, &ts);
+ pthread_cond_timedwait(&ri->cond, &_res_cache_list_lock, &ts);
+ /* Must update *cache as it could have been deleted. */
+ *cache = _find_named_cache_locked(netid);
}
}
@@ -1325,17 +1335,25 @@ _cache_notify_waiting_tid_locked( struct resolv_cache* cache, Entry* key )
/* notify the cache that the query failed */
void
-_resolv_cache_query_failed( struct resolv_cache* cache,
+_resolv_cache_query_failed( unsigned netid,
const void* query,
int querylen)
{
Entry key[1];
+ Cache* cache;
+
+ if (!entry_init_key(key, query, querylen))
+ return;
+
+ pthread_mutex_lock(&_res_cache_list_lock);
+
+ cache = _find_named_cache_locked(netid);
- if (cache && entry_init_key(key, query, querylen)) {
- pthread_mutex_lock(&cache->lock);
+ if (cache) {
_cache_notify_waiting_tid_locked(cache, key);
- pthread_mutex_unlock(&cache->lock);
}
+
+ pthread_mutex_unlock(&_res_cache_list_lock);
}
static void
@@ -1391,7 +1409,6 @@ _resolv_cache_create( void )
cache->max_entries = _res_cache_get_max_entries();
cache->entries = calloc(sizeof(*cache->entries), cache->max_entries);
if (cache->entries) {
- pthread_mutex_init( &cache->lock, NULL );
cache->mru_list.mru_prev = cache->mru_list.mru_next = &cache->mru_list;
XLOG("%s: cache created\n", __FUNCTION__);
} else {
@@ -1586,7 +1603,7 @@ static void _cache_remove_expired(Cache* cache) {
}
ResolvCacheStatus
-_resolv_cache_lookup( struct resolv_cache* cache,
+_resolv_cache_lookup( unsigned netid,
const void* query,
int querylen,
void* answer,
@@ -1597,6 +1614,7 @@ _resolv_cache_lookup( struct resolv_cache* cache,
Entry** lookup;
Entry* e;
time_t now;
+ Cache* cache;
ResolvCacheStatus result = RESOLV_CACHE_NOTFOUND;
@@ -1609,7 +1627,14 @@ _resolv_cache_lookup( struct resolv_cache* cache,
return RESOLV_CACHE_UNSUPPORTED;
}
/* lookup cache */
- pthread_mutex_lock( &cache->lock );
+ pthread_once(&_res_cache_once, _res_cache_init);
+ pthread_mutex_lock(&_res_cache_list_lock);
+
+ cache = _find_named_cache_locked(netid);
+ if (cache == NULL) {
+ result = RESOLV_CACHE_UNSUPPORTED;
+ goto Exit;
+ }
/* see the description of _lookup_p to understand this.
* the function always return a non-NULL pointer.
@@ -1621,7 +1646,7 @@ _resolv_cache_lookup( struct resolv_cache* cache,
XLOG( "NOT IN CACHE");
// calling thread will wait if an outstanding request is found
// that matching this query
- if (!_cache_check_pending_request_locked(cache, key)) {
+ if (!_cache_check_pending_request_locked(&cache, key, netid) || cache == NULL) {
goto Exit;
} else {
lookup = _cache_lookup_p(cache, key);
@@ -1662,13 +1687,13 @@ _resolv_cache_lookup( struct resolv_cache* cache,
result = RESOLV_CACHE_FOUND;
Exit:
- pthread_mutex_unlock( &cache->lock );
+ pthread_mutex_unlock(&_res_cache_list_lock);
return result;
}
void
-_resolv_cache_add( struct resolv_cache* cache,
+_resolv_cache_add( unsigned netid,
const void* query,
int querylen,
const void* answer,
@@ -1678,6 +1703,7 @@ _resolv_cache_add( struct resolv_cache* cache,
Entry* e;
Entry** lookup;
u_long ttl;
+ Cache* cache = NULL;
/* don't assume that the query has already been cached
*/
@@ -1686,7 +1712,12 @@ _resolv_cache_add( struct resolv_cache* cache,
return;
}
- pthread_mutex_lock( &cache->lock );
+ pthread_mutex_lock(&_res_cache_list_lock);
+
+ cache = _find_named_cache_locked(netid);
+ if (cache == NULL) {
+ goto Exit;
+ }
XLOG( "%s: query:", __FUNCTION__ );
XLOG_QUERY(query,querylen);
@@ -1732,8 +1763,10 @@ _resolv_cache_add( struct resolv_cache* cache,
_cache_dump_mru(cache);
#endif
Exit:
- _cache_notify_waiting_tid_locked(cache, key);
- pthread_mutex_unlock( &cache->lock );
+ if (cache != NULL) {
+ _cache_notify_waiting_tid_locked(cache, key);
+ }
+ pthread_mutex_unlock(&_res_cache_list_lock);
}
/****************************************************************************/
@@ -1744,20 +1777,13 @@ Exit:
/****************************************************************************/
/****************************************************************************/
-static pthread_once_t _res_cache_once = PTHREAD_ONCE_INIT;
-
// Head of the list of caches. Protected by _res_cache_list_lock.
static struct resolv_cache_info _res_cache_list;
-// lock protecting everything in the _resolve_cache_info structs (next ptr, etc)
-static pthread_mutex_t _res_cache_list_lock;
-
/* insert resolv_cache_info into the list of resolv_cache_infos */
static void _insert_cache_info_locked(struct resolv_cache_info* cache_info);
/* creates a resolv_cache_info */
static struct resolv_cache_info* _create_cache_info( void );
-/* gets cache associated with a network, or NULL if none exists */
-static struct resolv_cache* _find_named_cache_locked(unsigned netid);
/* gets a resolv_cache_info associated with a network, or NULL if not found */
static struct resolv_cache_info* _find_cache_info_locked(unsigned netid);
/* look up the named cache, and creates one if needed */
@@ -1785,22 +1811,6 @@ _res_cache_init(void)
pthread_mutex_init(&_res_cache_list_lock, NULL);
}
-struct resolv_cache*
-__get_res_cache(unsigned netid)
-{
- struct resolv_cache *cache;
-
- pthread_once(&_res_cache_once, _res_cache_init);
- pthread_mutex_lock(&_res_cache_list_lock);
-
- /* Does NOT create a cache if it does not exist. */
- cache = _find_named_cache_locked(netid);
-
- pthread_mutex_unlock(&_res_cache_list_lock);
- XLOG("%s: netid=%u, cache=%p\n", __FUNCTION__, netid, cache);
- return cache;
-}
-
static struct resolv_cache*
_get_res_cache_for_net_locked(unsigned netid)
{
@@ -1837,12 +1847,36 @@ _flush_cache_for_net_locked(unsigned netid)
{
struct resolv_cache* cache = _find_named_cache_locked(netid);
if (cache) {
- pthread_mutex_lock(&cache->lock);
_cache_flush_locked(cache);
- pthread_mutex_unlock(&cache->lock);
}
}
+void _resolv_delete_cache_for_net(unsigned netid)
+{
+ pthread_once(&_res_cache_once, _res_cache_init);
+ pthread_mutex_lock(&_res_cache_list_lock);
+
+ struct resolv_cache_info* prev_cache_info = &_res_cache_list;
+
+ while (prev_cache_info->next) {
+ struct resolv_cache_info* cache_info = prev_cache_info->next;
+
+ if (cache_info->netid == netid) {
+ prev_cache_info->next = cache_info->next;
+ _cache_flush_locked(cache_info->cache);
+ free(cache_info->cache->entries);
+ free(cache_info->cache);
+ _free_nameservers_locked(cache_info);
+ free(cache_info);
+ break;
+ }
+
+ prev_cache_info = prev_cache_info->next;
+ }
+
+ pthread_mutex_unlock(&_res_cache_list_lock);
+}
+
static struct resolv_cache_info*
_create_cache_info(void)
{
diff --git a/libc/dns/resolv/res_send.c b/libc/dns/resolv/res_send.c
index de09385..6439e31 100644
--- a/libc/dns/resolv/res_send.c
+++ b/libc/dns/resolv/res_send.c
@@ -367,7 +367,6 @@ res_nsend(res_state statp,
int gotsomewhere, terrno, try, v_circuit, resplen, ns, n;
char abuf[NI_MAXHOST];
#if USE_RESOLV_CACHE
- struct resolv_cache* cache;
ResolvCacheStatus cache_status = RESOLV_CACHE_UNSUPPORTED;
#endif
@@ -389,21 +388,17 @@ res_nsend(res_state statp,
terrno = ETIMEDOUT;
#if USE_RESOLV_CACHE
- // get the cache associated with the network
- cache = __get_res_cache(statp->netid);
- if (cache != NULL) {
- int anslen = 0;
- cache_status = _resolv_cache_lookup(
- cache, buf, buflen,
- ans, anssiz, &anslen);
-
- if (cache_status == RESOLV_CACHE_FOUND) {
- return anslen;
- } else {
- // had a cache miss for a known network, so populate the thread private
- // data so the normal resolve path can do its thing
- _resolv_populate_res_for_net(statp);
- }
+ int anslen = 0;
+ cache_status = _resolv_cache_lookup(
+ statp->netid, buf, buflen,
+ ans, anssiz, &anslen);
+
+ if (cache_status == RESOLV_CACHE_FOUND) {
+ return anslen;
+ } else if (cache_status != RESOLV_CACHE_UNSUPPORTED) {
+ // had a cache miss for a known network, so populate the thread private
+ // data so the normal resolve path can do its thing
+ _resolv_populate_res_for_net(statp);
}
if (statp->nscount == 0) {
@@ -602,7 +597,7 @@ res_nsend(res_state statp,
#if USE_RESOLV_CACHE
if (cache_status == RESOLV_CACHE_NOTFOUND) {
- _resolv_cache_add(cache, buf, buflen,
+ _resolv_cache_add(statp->netid, buf, buflen,
ans, resplen);
}
#endif
@@ -658,13 +653,13 @@ res_nsend(res_state statp,
errno = terrno;
#if USE_RESOLV_CACHE
- _resolv_cache_query_failed(cache, buf, buflen);
+ _resolv_cache_query_failed(statp->netid, buf, buflen);
#endif
return (-1);
fail:
#if USE_RESOLV_CACHE
- _resolv_cache_query_failed(cache, buf, buflen);
+ _resolv_cache_query_failed(statp->netid, buf, buflen);
#endif
res_nclose(statp);
return (-1);
@@ -951,7 +946,7 @@ connect_with_timeout(int sock, const struct sockaddr *nsap, socklen_t salen, int
origflags = fcntl(sock, F_GETFL, 0);
fcntl(sock, F_SETFL, origflags | O_NONBLOCK);
- res = connect(sock, nsap, salen);
+ res = __connect(sock, nsap, salen);
if (res < 0 && errno != EINPROGRESS) {
res = -1;
goto done;
@@ -1108,7 +1103,7 @@ send_dg(res_state statp,
res_nclose(statp);
return (0);
}
- if (connect(EXT(statp).nssocks[ns], nsap, (socklen_t)nsaplen) < 0) {
+ if (__connect(EXT(statp).nssocks[ns], nsap, (socklen_t)nsaplen) < 0) {
Aerror(statp, stderr, "connect(dg)", errno, nsap,
nsaplen);
res_nclose(statp);
diff --git a/libc/kernel/uapi/linux/ion.h b/libc/kernel/uapi/linux/ion.h
index f18939d..5af39d0 100644
--- a/libc/kernel/uapi/linux/ion.h
+++ b/libc/kernel/uapi/linux/ion.h
@@ -16,56 +16,63 @@
***
****************************************************************************
****************************************************************************/
-#ifndef _LINUX_ION_H
-#define _LINUX_ION_H
+#ifndef _UAPI_LINUX_ION_H
+#define _UAPI_LINUX_ION_H
+#include <linux/ioctl.h>
#include <linux/types.h>
-struct ion_handle;
/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
+typedef int ion_user_handle_t;
enum ion_heap_type {
ION_HEAP_TYPE_SYSTEM,
ION_HEAP_TYPE_SYSTEM_CONTIG,
- ION_HEAP_TYPE_CARVEOUT,
/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
+ ION_HEAP_TYPE_CARVEOUT,
+ ION_HEAP_TYPE_CHUNK,
+ ION_HEAP_TYPE_DMA,
ION_HEAP_TYPE_CUSTOM,
+/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
ION_NUM_HEAPS = 16,
};
#define ION_HEAP_SYSTEM_MASK (1 << ION_HEAP_TYPE_SYSTEM)
-/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
#define ION_HEAP_SYSTEM_CONTIG_MASK (1 << ION_HEAP_TYPE_SYSTEM_CONTIG)
+/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
#define ION_HEAP_CARVEOUT_MASK (1 << ION_HEAP_TYPE_CARVEOUT)
+#define ION_HEAP_TYPE_DMA_MASK (1 << ION_HEAP_TYPE_DMA)
+#define ION_NUM_HEAP_IDS sizeof(unsigned int) * 8
#define ION_FLAG_CACHED 1
-#define ION_FLAG_CACHED_NEEDS_SYNC 2
/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
+#define ION_FLAG_CACHED_NEEDS_SYNC 2
struct ion_allocation_data {
size_t len;
size_t align;
- unsigned int heap_mask;
/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
+ unsigned int heap_id_mask;
unsigned int flags;
- struct ion_handle *handle;
+ ion_user_handle_t handle;
};
-struct ion_fd_data {
/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
- struct ion_handle *handle;
+struct ion_fd_data {
+ ion_user_handle_t handle;
int fd;
};
-struct ion_handle_data {
/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
- struct ion_handle *handle;
+struct ion_handle_data {
+ ion_user_handle_t handle;
};
struct ion_custom_data {
- unsigned int cmd;
/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
+ unsigned int cmd;
unsigned long arg;
};
#define ION_IOC_MAGIC 'I'
-#define ION_IOC_ALLOC _IOWR(ION_IOC_MAGIC, 0, struct ion_allocation_data)
/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
+#define ION_IOC_ALLOC _IOWR(ION_IOC_MAGIC, 0, struct ion_allocation_data)
#define ION_IOC_FREE _IOWR(ION_IOC_MAGIC, 1, struct ion_handle_data)
#define ION_IOC_MAP _IOWR(ION_IOC_MAGIC, 2, struct ion_fd_data)
#define ION_IOC_SHARE _IOWR(ION_IOC_MAGIC, 4, struct ion_fd_data)
-#define ION_IOC_IMPORT _IOWR(ION_IOC_MAGIC, 5, struct ion_fd_data)
/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */
+#define ION_IOC_IMPORT _IOWR(ION_IOC_MAGIC, 5, struct ion_fd_data)
#define ION_IOC_SYNC _IOWR(ION_IOC_MAGIC, 7, struct ion_fd_data)
#define ION_IOC_CUSTOM _IOWR(ION_IOC_MAGIC, 6, struct ion_custom_data)
#endif
+/* WARNING: DO NOT EDIT, AUTO-GENERATED CODE - SEE TOP FOR INSTRUCTIONS */